# https://github.com/haris-musa/excel-mcp-server 项目说明书 生成时间：2026-06-21 06:13:38 UTC ## 目录 - [Project Overview & Architecture](#page-1) - [Tools & API Reference](#page-2) - [Transport, Configuration & Deployment](#page-3) - [Security, Validation & Operations](#page-4) ## Project Overview & Architecture ### 相关页面 相关主题：[Tools & API Reference](#page-2), [Transport, Configuration & Deployment](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/haris-musa/excel-mcp-server/blob/main/README.md) - [manifest.json](https://github.com/haris-musa/excel-mcp-server/blob/main/manifest.json) - [TOOLS.md](https://github.com/haris-musa/excel-mcp-server/blob/main/TOOLS.md) - [src/excel_mcp/server.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/server.py) - [src/excel_mcp/calculations.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/calculations.py) - [src/excel_mcp/validation.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/validation.py) - [src/excel_mcp/formatting.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/formatting.py) - [src/excel_mcp/sheet.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/sheet.py) - [src/excel_mcp/workbook.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/workbook.py) - [src/excel_mcp/pivot.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/pivot.py)
# 项目概述与架构 ## 项目目标与核心能力 Excel MCP Server 是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的开源服务器，使 AI Agent 能够以工具调用方式创建、读取与修改 Excel 工作簿，全程无需在本地安装 Microsoft Excel。资料来源：[README.md:9-11]()。项目核心能力覆盖工作簿生命周期管理、单元格读写、公式应用与校验、样式与条件格式、图表、数据透视表以及 Excel 原生表格。资料来源：[README.md:13-22]()。 根据 `manifest.json` 的声明，服务器当前发布版本为 0.1.8，通过 `uvx excel-mcp-server stdio` 启动；`tools` 数组共声明了约 24 个 MCP 工具，覆盖 `create_workbook`、`apply_formula`、`create_chart`、`create_pivot_table` 等高频操作。资料来源：[manifest.json:1-48]()。 ## 系统架构 服务器以 FastMCP 作为底层框架，通过 `@mcp.tool` 装饰器将各功能模块注册为 MCP 工具。`server.py` 是统一入口，所有工具函数都遵循「路径解析 → 参数校验 → 调用实现层 → 异常转换」的固定模式，例如 `apply_formula` 在写入前会先调用 `validate_formula_impl` 进行预校验，仅在校验通过后才落入 `calculations.py` 的实现层。资料来源：[server.py:30-100]()。路径解析统一通过 `get_excel_path(filepath)` 完成，业务异常（`ValidationError`、`WorkbookError`、`SheetError` 等）被捕获并转换为字符串消息返回给调用方。资料来源：[server.py:50-60]()。 ```mermaid flowchart LR Client[MCP 客户端
Claude Desktop / Cursor] -->|JSON-RPC| Server[server.py
FastMCP 实例] Server --> Workbook[workbook.py] Server --> Sheet[sheet.py] Server --> Data[data.py] Server --> Calc[calculations.py] Server --> Valid[validation.py] Server --> Format[formatting.py] Server --> Chart[chart.py] Server --> Pivot[pivot.py] Server --> Tables[tables.py] Workbook --> XLSX[(Excel 文件
基于 openpyxl)] Sheet --> XLSX Data --> XLSX Calc --> XLSX Format --> XLSX Chart --> XLSX Pivot --> XLSX Tables --> XLSX ``` ## 模块与职责划分 项目在 `src/excel_mcp/` 目录下按业务域拆分实现，每个模块对应一类工具操作，职责清晰且边界明确： | 模块 | 主要职责 | 关键实现 | |------|----------|----------| | `workbook.py` | 工作簿生命周期管理 | `create_workbook` 在保存前自动创建父目录。资料来源：[workbook.py:14-30]() | | `sheet.py` | 工作表结构与合并操作 | `copy_sheet`、`merge_range`、`insert_row`、`delete_rows`。资料来源：[sheet.py:1-40]() | | `data.py` | 单元格读写 | `read_data`、`write_data`（含范围解析） | | `calculations.py` | 公式应用 | `apply_formula` 强制公式以 `=` 开头并依赖 `validate_formula` 预校验。资料来源：[calculations.py:1-40]() | | `validation.py` | 公式与范围校验 | 拒绝 `HYPERLINK`、`WEBSERVICE`、`DGET`、`RTD` 等不安全函数。资料来源：[validation.py:1-30]() | | `formatting.py` | 字体、边框、条件格式 | `format_range` 支持颜色、合并、保护等属性。资料来源：[formatting.py:1-30]() | | `pivot.py` | 数据透视表 | 通过 `openpyxl` 的 `Table` 对象模拟透视表输出。资料来源：[pivot.py:1-25]() | | `exceptions.py` | 统一异常体系 | `ValidationError`、`WorkbookError`、`SheetError`、`DataError` 等 | ## 传输机制与已知安全风险 README 声明服务器支持三种传输方式：`stdio`（本地）、`SSE`（已弃用）与 `streamable HTTP`（远程）。资料来源：[README.md:23-60]()。在 v0.1.8 发布中，项目修复了 SSE / streamable HTTP 传输中的路径穿越漏洞。资料来源：[v0.1.8 Release Notes](https://github.com/haris-musa/excel-mcp-server/releases/tag/v0.1.8)。 社区与安全研究者指出，仍有以下风险需运维方关注： - 任意文件路径访问：`create_workbook` 等工具接受任意 `filepath`，在 stdio 模式下对本地文件系统具有无限制写权限。资料来源：[issue #120](https://github.com/haris-musa/excel-mcp-server/issues/120)、[issue #131](https://github.com/haris-musa/excel-mcp-server/issues/131) - 公式注入旁路：`write_data_to_excel` 写入的字符串可直接绕过 `apply_formula` 的不安全函数校验。资料来源：[issue #134](https://github.com/haris-musa/excel-mcp-server/issues/134) - 命令注入：`mcpfuzz` 扫描报告 `create_workbook` 存在严重命令注入风险，另有 22 个工具的路径参数存在净化缺失警告。资料来源：[issue #128](https://github.com/haris-musa/excel-mcp-server/issues/128) - 调用者身份缺失：服务器目前无法区分多个 Claude Desktop 用户的工具调用来源，缺乏审计追踪能力。资料来源：[issue #138](https://github.com/haris-musa/excel-mcp-server/issues/138) v0.1.8 引入了 `ToolAnnotations`（`destructiveHint`、`readOnlyHint`），为 LLM 客户端提供工具语义提示，但尚未提供强制访问控制策略。资料来源：[server.py:35-51]()。 ## 参见 - 工具参考：[TOOLS.md](https://github.com/haris-musa/excel-mcp-server/blob/main/TOOLS.md) - 服务器清单：[manifest.json](https://github.com/haris-musa/excel-mcp-server/blob/main/manifest.json) - MCP 协议规范：[modelcontextprotocol.io](https://modelcontextprotocol.io/) - FastMCP 框架：[github.com/jlowin/fastmcp](https://github.com/jlowin/fastmcp) --- ## Tools & API Reference ### 相关页面 相关主题：[Project Overview & Architecture](#page-1), [Transport, Configuration & Deployment](#page-3), [Security, Validation & Operations](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [TOOLS.md](https://github.com/haris-musa/excel-mcp-server/blob/main/TOOLS.md) - [manifest.json](https://github.com/haris-musa/excel-mcp-server/blob/main/manifest.json) - [README.md](https://github.com/haris-musa/excel-mcp-server/blob/main/README.md) - [src/excel_mcp/server.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/server.py) - [src/excel_mcp/workbook.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/workbook.py) - [src/excel_mcp/sheet.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/sheet.py) - [src/excel_mcp/calculations.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/calculations.py) - [src/excel_mcp/validation.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/validation.py) - [src/excel_mcp/formatting.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/formatting.py) - [src/excel_mcp/pivot.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/pivot.py)
# Tools & API Reference ## 概述 excel-mcp-server 是一个基于 Model Context Protocol (MCP) 的服务器，向上层 AI 智能体（Claude Desktop、Ontheia 等）暴露一组以 Excel 文件为操作对象的工具（tools）。所有工具的注册入口位于 [src/excel_mcp/server.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/server.py)，该模块通过 `FastMCP` 实例统一注册，并使用 `ToolAnnotations` 为每个工具打上 `destructiveHint` / `readOnlyHint` 等元数据以帮助大模型理解其副作用（资料来源：[src/excel_mcp/server.py]()）。 按 [manifest.json](https://github.com/haris-musa/excel-mcp-server/blob/main/manifest.json) 的 `tools` 列表，server 暴露了约 20+ 个工具，覆盖工作簿（workbook）、工作表（worksheet）、数据读写、公式、格式化、图表、数据透视表、Excel 原生表（Table）以及行列增删等功能。整体调用流程如下： ```mermaid flowchart LR A[MCP Client
Claude/Ontheia] -->|JSON-RPC| B[FastMCP
server.py] B --> C[Validation Layer
validation.py] C --> D[Domain Modules
workbook / sheet /
data / calculations /
formatting / chart / pivot / tables] D --> E[(openpyxl
xlsx files)] ``` ## 工具分类与职责 ### 工作簿与工作表管理 工作簿级别的操作集中在 [src/excel_mcp/workbook.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/workbook.py) 中实现，核心工具包括 `create_workbook`、`create_worksheet`、`get_workbook_metadata`。其中 `create_workbook` 默认创建名为 `Sheet1` 的工作表，若路径不存在则自动创建父目录（资料来源：[src/excel_mcp/workbook.py]()）；`get_or_create_workbook` 是内部辅助函数，在文件不存在时回退到创建逻辑，以支持 `apply_formula` 等“先取后写”场景。 工作表级别的工具——`copy_worksheet`、`delete_worksheet`、`rename_worksheet`、`merge_cells`、`unmerge_cells`、`get_merged_cells`、`insert_rows`、`insert_columns`、`delete_sheet_rows`、`delete_sheet_columns`、`copy_range`、`delete_range`——均由 [src/excel_mcp/sheet.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/sheet.py) 提供实现（资料来源：[src/excel_mcp/sheet.py]()）。这些工具在 [TOOLS.md](https://github.com/haris-musa/excel-mcp-server/blob/main/TOOLS.md) 中均以 `filepath`、`sheet_name`、`start_cell` / `end_cell` 等统一参数风格暴露给 LLM。 ### 数据读写 `read_data_from_excel` 与 `write_data_to_excel` 是最常用的两个数据交互工具，二者签名（如 `start_cell` 默认 `"A1"`）定义在 [TOOLS.md](https://github.com/haris-musa/excel-mcp-server/blob/main/TOOLS.md) 中。`write_data_to_excel` 接收 `List[Dict]` 结构化数据并按起始单元格写入；`read_data_from_excel` 则可附带数据验证元信息（validations）一并返回（资料来源：[TOOLS.md]()）。 ### 公式与计算 `apply_formula` 与 `validate_formula_syntax` 通过 [src/excel_mcp/server.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/server.py) 注册到 MCP 端点。底层实现在 [src/excel_mcp/calculations.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/calculations.py) 中：函数会先调用 `validate_cell_reference`，再通过 `validate_formula` 做语法与安全检查，最后由 `openpyxl` 写入并 `wb.save()` 落盘（资料来源：[src/excel_mcp/calculations.py]()）。 ### 公式安全校验 由于公式注入是社区关注的高危面，校验逻辑被独立抽取至 [src/excel_mcp/validation.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/validation.py)。`validate_formula_in_cell_operation` 会先进行语法与函数白名单检查，再使用正则 `r'[A-Z]+[0-9]+(?::[A-Z]+[0-9]+)?'` 提取公式中的单元格引用并逐一校验；`validate_range_bounds` 则约束范围不能越界（资料来源：[src/excel_mcp/validation.py]()）。 ### 格式化、图表与透视表 `format_range` 由 [src/excel_mcp/formatting.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/formatting.py) 实现，覆盖字体、边框、底纹、对齐、条件格式、保护属性等，并支持在同一次调用中合并单元格（资料来源：[src/excel_mcp/formatting.py]()）。`create_chart` 通过 `create_chart_in_sheet` 暴露，支持 `line/bar/pie/scatter` 等类型；`create_pivot_table` 由 [src/excel_mcp/pivot.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/pivot.py) 实现，参数包括 `rows / values / columns / agg_func`，并要求 `data_range` 必须以 `A1:B2` 形式给出（资料来源：[src/excel_mcp/pivot.py]()）。 ## 工具元数据与错误模型 每个工具均通过 `ToolAnnotations` 显式声明 `destructiveHint` 或 `readOnlyHint`：写操作（如 `create_workbook`、`write_data_to_excel`、`apply_formula`、`format_range`、`merge_cells` 等）被标记为 `destructiveHint=True`，只读工具（如 `get_workbook_metadata`、`get_merged_cells`、`validate_excel_range`、`validate_formula_syntax`）被标记为 `readOnlyHint=True`（资料来源：[src/excel_mcp/server.py]()）。 错误处理方面，[src/excel_mcp/exceptions.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/exceptions.py) 定义了 `ValidationError`、`WorkbookError`、`SheetError`、`DataError`、`FormattingError`、`CalculationError`、`PivotError`、`ChartError` 等领域异常。工具函数通常将已知业务异常以 `f"Error: {str(e)}"` 形式直接返回给调用方，而将意外异常透传给上层日志（资料来源：[src/excel_mcp/server.py]()）。 ## 已知限制与社区关注 虽然 [TOOLS.md](https://github.com/haris-musa/excel-mcp-server/blob/main/TOOLS.md) 提供了相对完整的 API 表面，但社区在多个 issue 中仍指出以下风险，集成时需重点评估： - **任意文件路径访问**：`create_workbook` 等工具以 `filepath` 作为参数且不进行沙箱校验，在 stdio 模式下等同于对宿主本地文件系统的写权限（参见 issue #120、#128、#131）。 - **公式注入绕过**：`write_data_to_excel` 与 `apply_formula` 共用相同写入路径，但 issue #134 报告前者在某些场景下可绕过 `apply_formula` 的 `unsafe_funcs` 黑名单。 - **多用户溯源缺失**：issue #138 指出当前工具调用没有绑定调用者身份，部署到多用户环境时无法做审计与授权。 - **历史兼容性回归**：issue #76 报告 `FastMCP.__init__()` 在 v0.1.5 之后新增了 `version` 参数，需对齐依赖版本。 ## 工具速查表 | 类别 | 工具示例 | 副作用 | 实现位置 | | --- | --- | --- | --- | | 工作簿 | `create_workbook`, `get_workbook_metadata` | 写 / 只读 | [workbook.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/workbook.py) | | 工作表 | `copy_worksheet`, `insert_rows`, `merge_cells` | 写 | [sheet.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/sheet.py) | | 数据 | `read_data_from_excel`, `write_data_to_excel` | 写 / 只读 | [TOOLS.md](https://github.com/haris-musa/excel-mcp-server/blob/main/TOOLS.md) | | 公式 | `apply_formula`, `validate_formula_syntax` | 写 / 只读 | [calculations.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/calculations.py) | | 格式化 | `format_range` | 写 | [formatting.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/formatting.py) | | 图表 / 透视 | `create_chart`, `create_pivot_table` | 写 | [pivot.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/pivot.py) | ## 参见 - [README.md](https://github.com/haris-musa/excel-mcp-server/blob/main/README.md) — 项目总览与传输方式（stdio / SSE / streamable-HTTP） - [manifest.json](https://github.com/haris-musa/excel-mcp-server/blob/main/manifest.json) — MCPB 安装清单与声明的工具列表 - [GitHub Issues · haris-musa/excel-mcp-server](https://github.com/haris-musa/excel-mcp-server/issues) — 安全审计、客户端兼容性与版本兼容性问题汇总 --- ## Transport, Configuration & Deployment ### 相关页面 相关主题：[Project Overview & Architecture](#page-1), [Security, Validation & Operations](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/haris-musa/excel-mcp-server/blob/main/README.md) - [manifest.json](https://github.com/haris-musa/excel-mcp-server/blob/main/manifest.json) - [src/excel_mcp/__main__.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/__main__.py) - [src/excel_mcp/server.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/server.py) - [src/excel_mcp/validation.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/validation.py) - [src/excel_mcp/workbook.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/workbook.py) - [TOOLS.md](https://github.com/haris-musa/excel-mcp-server/blob/main/TOOLS.md)
# Transport, Configuration & Deployment 本文档说明 excel-mcp-server 的传输协议、客户端配置方式以及部署模式，重点面向需要在本机或远程环境中接入该服务器的开发者与运维人员。 ## 传输协议概览 服务器实现三种 MCP 传输方式：stdio、SSE（已弃用）以及 streamable-HTTP，可在启动时通过命令行参数切换 [README.md:33-38]()。stdio 是 Claude Desktop、Cursor 等本地客户端的默认通道，启动后通过标准输入输出交换 JSON-RPC 消息，无需额外网络监听 [manifest.json:17-22]()。 ```bash uvx excel-mcp-server stdio # 本地直连 uvx excel-mcp-server sse # 已弃用 uvx excel-mcp-server streamable-http # 远程服务（v0.1.5 引入） ``` SSE 传输自 v0.1.5 起被 streamable-HTTP 取代，但出于向后兼容仍在入口保留 [Release v0.1.5]()。v0.1.7 修复了 streamable-HTTP 启动时的主机与端口配置问题 [Release v0.1.7]()。 ## 服务器初始化与工具注册 服务器入口位于 `src/excel_mcp/__main__.py`，由 `src/excel_mcp/server.py` 中的 `FastMCP` 实例加载并注册全部 20 多个工具 [manifest.json:24-46]()。日志文件路径硬编码为项目根目录下的 `excel-mcp.log`，避免 stdio 模式下因客户端工作目录不可写而导致启动失败 [src/excel_mcp/server.py:48-52]()。 每个工具通过 `@mcp.tool(annotations=ToolAnnotations(...))` 装饰器注册，明确声明 `destructiveHint`、`readOnlyHint` 等元数据，使 LLM 与 UI 能区分危险操作 [src/excel_mcp/server.py:7-15]()。例如： ```python @mcp.tool(annotations=ToolAnnotations(title="Apply Formula", destructiveHint=True)) def apply_formula(filepath: str, sheet_name: str, cell: str, formula: str) -> str: ... ``` 这种注解机制随 v0.1.8 一并引入，是改善工具可发现性的重要变更 [Release v0.1.8]()。 ## 客户端集成配置 ### 本地客户端（stdio） Claude Desktop 通过 `mcpServers` JSON 配置启动进程，manifest.json 中的 `mcp_config` 字段采用相同结构以便一键导入 [manifest.json:17-22]()： ```json { "mcpServers": { "excel": { "command": "uvx", "args": ["excel-mcp-server", "stdio"] } } } ``` Cursor 提供官方 deeplink 安装按钮，配置内容与上述一致 [README.md:18-19]()。 ### 远程部署（streamable-HTTP） 远程场景下，服务器监听 HTTP 端口接收请求。v0.1.8 修复了 SSE/streamable-http 传输中的路径遍历漏洞，部署者必须升级以避免任意文件读取 [Release v0.1.8 / Issue #128]()。容器化部署（Docker）目前由社区请求，官方尚未发布镜像 [Issue #10]()。 | 部署维度 | stdio | streamable-HTTP | |---|---|---| | 鉴权 | 依赖宿主机用户 | 需在网络层加固 | | 文件访问范围 | 受启动用户权限限制 | 服务进程权限即全部 | | 适用场景 | 单机本地代理 | 多客户端共享 | | 已知风险 | 命令注入 [Issue #128]() | 路径遍历（v0.1.8 已修） | ## 部署安全注意事项 服务器暴露约 20 个写文件工具，在 stdio 模式下具备本机文件系统完全写入权限，社区已识别多项关键风险： 1. **任意文件路径访问**：`create_workbook`、`write_data_to_excel` 等工具接受任意 `filepath`，可能被间接提示注入利用 [Issue #120]()。 2. **公式注入绕过**：`write_data_to_excel` 不经过 `apply_formula` 中的 `unsafe_funcs` 黑名单校验（如 `HYPERLINK`、`WEBSERVICE`），可写入危险公式 [src/excel_mcp/validation.py:1-15]()，[Issue #134]()。 3. **命令注入**：mcpfuzz 扫描发现 `create_workbook` 存在严重命令注入漏洞，另有 22 个工具因路径未净化被标记 [Issue #128]()。 4. **策略执行缺失**：建议为写文件工具加入路径白名单与写权限策略 [Issue #131]()。 5. **用户身份不可识别**：服务器无法区分多客户端调用者身份，无法审计或鉴权 [Issue #138]()。 工作簿写入通过 `src/excel_mcp/workbook.py` 中的 `Path.parent.mkdir(parents=True, exist_ok=True)` 自动创建父目录，这在受限环境下可能产生意外写入 [src/excel_mcp/workbook.py:14-19]()。部署建议：在容器或 chroot 中运行 streamable-HTTP 模式、限制可访问目录、为危险工具配置额外 ACL。 ## 兼容性与已知故障 - **macOS + Codex**：Issue #100 报告 Codex 启动 stdio 时报 `No such file or directory (os error 2)`，通常由 `uvx` 未在 PATH 中或工作目录权限异常引起 [Issue #100]()。 - **FastMCP 兼容性**：v0.1.6 修复了 `FastMCP.__init__()` 不支持 `version` 参数导致的 `TypeError` [Release v0.1.6 / Issue #76]()。 - **第三方客户端兼容**：Ontheia、Joy Trust Network、powerpoint.md 已收录并验证 [Issue #132 / #129 / #123]()。 - **打包格式**：v0.1.8 新增 MCPB 打包，可用于 Claude Desktop 一键安装 [Release v0.1.8]()。 ## 参见 - 工具完整列表与参数：[TOOLS.md]() - 工作簿创建与路径处理：[src/excel_mcp/workbook.py]() - 公式与范围安全校验：[src/excel_mcp/validation.py]() - 工具注册与注解：[src/excel_mcp/server.py]() --- ## Security, Validation & Operations ### 相关页面 相关主题：[Project Overview & Architecture](#page-1), [Tools & API Reference](#page-2), [Transport, Configuration & Deployment](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [TOOLS.md](https://github.com/haris-musa/excel-mcp-server/blob/main/TOOLS.md) - [manifest.json](https://github.com/haris-musa/excel-mcp-server/blob/main/manifest.json) - [src/excel_mcp/server.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/server.py) - [src/excel_mcp/validation.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/validation.py) - [src/excel_mcp/calculations.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/calculations.py) - [src/excel_mcp/cell_validation.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/cell_validation.py) - [README.md](https://github.com/haris-musa/excel-mcp-server/blob/main/README.md)
# 安全、验证与操作 ## 概述 excel-mcp-server 是一个基于 Model Context Protocol（MCP）的 Excel 文件操作服务器，可在不安装 Microsoft Excel 的前提下让 AI 代理创建、读取与修改工作簿。围绕"安全、验证与操作"这一主题，服务器在 MCP 工具层（[src/excel_mcp/server.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/server.py)）、业务逻辑层（[src/excel_mcp/validation.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/validation.py)、[src/excel_mcp/calculations.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/calculations.py)）与数据验证层（[src/excel_mcp/cell_validation.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/cell_validation.py)）共同提供输入校验、异常捕获与可观察能力。运行时通过 stdio、SSE（已弃用）和 streamable-HTTP 三种传输方式对外暴露（资料来源：[README.md:23-39](https://github.com/haris-musa/excel-mcp-server/blob/main/README.md#L23-L39)）。 ## 输入验证机制 服务器对三类关键输入进行验证：公式、单元格引用与范围边界。 **公式验证**：`validate_formula` 函数通过正则提取公式内的函数名，并与黑名单比对。黑名单中包含以下被认为不安全的函数： | 不安全函数 | 风险说明 | | --- | --- | | `HYPERLINK` | 可嵌入恶意链接 | | `WEBSERVICE` | 发起外部 HTTP 调用 | | `DGET` | 触发数据库查询 | | `RTD` | 实时数据通道外泄 | `apply_formula` 工具强制公式以 `=` 开头，并在写入前调用 `validate_formula_in_cell_operation` 二次校验单元格引用与公式语法（资料来源：[src/excel_mcp/calculations.py:18-44](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/calculations.py#L18-L44)）。 **范围与引用验证**：`validate_range_bounds` 检查起止行列是否落在工作表 `max_row` / `max_column` 范围内（资料来源：[src/excel_mcp/validation.py:60-90](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/validation.py#L60-L90)）；`validate_formula_in_cell_operation` 使用 `re.findall(r'[A-Z]+[0-9]+(?::[A-Z]+[0-9]+)?', formula)` 提取公式中的所有单元格与范围引用并逐个校验（资料来源：[src/excel_mcp/validation.py:38-58](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/validation.py#L38-L58)）。 **数据验证元数据**：读取数据时，`read_data_from_excel` 可附带每个单元格的数据验证信息，包含验证类型、操作符、下拉列表允许值、公式约束、提示与错误信息（[src/excel_mcp/cell_validation.py](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/cell_validation.py)）。 ## 安全风险与社区共识 v0.1.8 修复了 SSE/streamable-HTTP 传输层的路径遍历漏洞（[release notes](https://github.com/haris-musa/excel-mcp-server/releases/tag/v0.1.8)），但社区安全审计仍指出若干待解决问题： - **任意文件路径访问**：`create_workbook` 与约 20 个写入工具接受未净化的文件路径，可能写入预期外的位置（[Issue #120](https://github.com/haris-musa/excel-mcp-server/issues/120)、[#128](https://github.com/haris-musa/excel-mcp-server/issues/128)）。 - **公式注入绕过**：`write_data_to_excel` 不复用 `apply_formula` 的公式黑名单校验，攻击者可借助 `data` 列表写入以 `=` 开头的危险公式（[Issue #134](https://github.com/haris-musa/excel-mcp-server/issues/134)）。 - **缺乏用户标识与策略强制**：stdio 模式下服务器对本地文件系统拥有完全写权限，且无法区分不同 MCP 客户端用户，缺少写操作的策略强制（[Issue #138](https://github.com/haris-musa/excel-mcp-server/issues/138)、[#131](https://github.com/haris-musa/excel-mcp-server/issues/131)）。 ## 操作行为与异常处理 服务器为每个工具声明 `ToolAnnotations`，明确其读写意图：`create_workbook`、`apply_formula`、`merge_cells`、`unmerge_cells`、`insert_rows`、`insert_columns`、`delete_sheet_rows` 标注 `destructiveHint=True`，而 `get_workbook_metadata`、`validate_formula_syntax`、`validate_excel_range`、`get_data_validation_info`、`get_merged_cells` 标注 `readOnlyHint=True`（资料来源：[src/excel_mcp/server.py:1-200](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/server.py#L1-L200)）。 异常体系分为 `ValidationError`、`WorkbookError`、`SheetError`、`DataError`、`FormattingError`、`CalculationError`、`PivotError`、`ChartError`，各业务模块抛出后由 MCP 装饰器统一捕获并返回 `"Error: ..."` 字符串，使 LLM 能够解析失败原因（资料来源：[src/excel_mcp/server.py:1-30](https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/server.py#L1-L30)）。 工具总数与分类在 [manifest.json](https://github.com/haris-musa/excel-mcp-server/blob/main/manifest.json) 中静态声明，涵盖工作簿、工作表、数据、公式、图表、数据透视表、表格与行/列操作。完整签名详见 [TOOLS.md](https://github.com/haris-musa/excel-mcp-server/blob/main/TOOLS.md)。 ## 参见 - [README.md](https://github.com/haris-musa/excel-mcp-server/blob/main/README.md) — 传输方式与启动说明 - [TOOLS.md](https://github.com/haris-musa/excel-mcp-server/blob/main/TOOLS.md) — 工具完整签名清单 - [Issues #120、#128、#131、#134、#138](https://github.com/haris-musa/excel-mcp-server/issues) — 安全审计与策略强制讨论 - [release v0.1.8](https://github.com/haris-musa/excel-mcp-server/releases/tag/v0.1.8) — 路径遍历漏洞修复 --- --- ## Doramagic 踩坑日志 项目：haris-musa/excel-mcp-server 摘要：发现 15 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Security consideration: Arbitrary file path access and unrestricted Excel formula injection。 ## 1. 安全/权限坑 · 来源证据：Security consideration: Arbitrary file path access and unrestricted Excel formula injection - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security consideration: Arbitrary file path access and unrestricted Excel formula injection - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/haris-musa/excel-mcp-server/issues/120 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 2. 安装坑 · 来源证据：Ontheia listed as compatible client — works great with excel-mcp-server - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Ontheia listed as compatible client — works great with excel-mcp-server - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/haris-musa/excel-mcp-server/issues/132 | 来源类型 github_issue 暴露的待验证使用条件。 ## 3. 安装坑 · 来源证据：Your MCP server is now indexed on Joy Trust Network - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Your MCP server is now indexed on Joy Trust Network - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/haris-musa/excel-mcp-server/issues/129 | 来源类型 github_issue 暴露的待验证使用条件。 ## 4. 安装坑 · 来源证据：Your skill is listed on powerpoint.md 🎉 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Your skill is listed on powerpoint.md 🎉 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/haris-musa/excel-mcp-server/issues/123 | 来源类型 github_issue 暴露的待验证使用条件。 ## 5. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/haris-musa/excel-mcp-server | host_targets=mcp_host, cursor ## 6. 配置坑 · 来源证据：Add policy enforcement for file write operations - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Add policy enforcement for file write operations - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/haris-musa/excel-mcp-server/issues/131 | 来源类型 github_issue 暴露的待验证使用条件。 ## 7. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/haris-musa/excel-mcp-server | README/documentation is current enough for a first validation pass. ## 8. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/haris-musa/excel-mcp-server | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/haris-musa/excel-mcp-server | no_demo; severity=medium ## 10. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/haris-musa/excel-mcp-server | no_demo; severity=medium ## 11. 安全/权限坑 · 来源证据：Security: Command Injection via unsanitized file path in create_workbook (+ 22 tools affected) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: Command Injection via unsanitized file path in create_workbook (+ 22 tools affected) - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/haris-musa/excel-mcp-server/issues/128 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 12. 安全/权限坑 · 来源证据：Security: know which user is calling your Excel MCP server? - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: know which user is calling your Excel MCP server? - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/haris-musa/excel-mcp-server/issues/138 | 来源类型 github_issue 暴露的待验证使用条件。 ## 13. 安全/权限坑 · 来源证据：write_data_to_excel can bypass unsafe formula validation - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：write_data_to_excel can bypass unsafe formula validation - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/haris-musa/excel-mcp-server/issues/134 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 14. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/haris-musa/excel-mcp-server | issue_or_pr_quality=unknown ## 15. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/haris-musa/excel-mcp-server | release_recency=unknown