项目概述与架构

项目目标与核心能力

Excel MCP Server 是一个基于 Model Context Protocol (MCP) 的开源服务器，使 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。

flowchart LR
    Client[MCP 客户端<br/>Claude Desktop / Cursor] -->|JSON-RPC| Server[server.py<br/>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 文件<br/>基于 openpyxl)]
    Sheet --> XLSX
    Data --> XLSX
    Calc --> XLSX
    Format --> XLSX
    Chart --> XLSX
    Pivot --> XLSX
    Tables --> XLSX

模块与职责划分

项目在 src/excel_mcp/ 目录下按业务域拆分实现，每个模块对应一类工具操作，职责清晰且边界明确：

传输机制与已知安全风险

README 声明服务器支持三种传输方式：stdio（本地）、SSE（已弃用）与 streamable HTTP（远程）。资料来源：README.md:23-60。在 v0.1.8 发布中，项目修复了 SSE / streamable HTTP 传输中的路径穿越漏洞。资料来源：v0.1.8 Release Notes。

社区与安全研究者指出，仍有以下风险需运维方关注：

• 任意文件路径访问：create_workbook 等工具接受任意 filepath，在 stdio 模式下对本地文件系统具有无限制写权限。资料来源：issue #120、issue #131
• 公式注入旁路：write_data_to_excel 写入的字符串可直接绕过 apply_formula 的不安全函数校验。资料来源：issue #134
• 命令注入：mcpfuzz 扫描报告 create_workbook 存在严重命令注入风险，另有 22 个工具的路径参数存在净化缺失警告。资料来源：issue #128
• 调用者身份缺失：服务器目前无法区分多个 Claude Desktop 用户的工具调用来源，缺乏审计追踪能力。资料来源：issue #138

v0.1.8 引入了 ToolAnnotations（destructiveHint、readOnlyHint），为 LLM 客户端提供工具语义提示，但尚未提供强制访问控制策略。资料来源：server.py:35-51。

参见

• 工具参考：TOOLS.md
• 服务器清单：manifest.json
• MCP 协议规范：modelcontextprotocol.io
• FastMCP 框架：github.com/jlowin/fastmcp

概述

excel-mcp-server 是一个基于 Model Context Protocol (MCP) 的服务器，向上层 AI 智能体（Claude Desktop、Ontheia 等）暴露一组以 Excel 文件为操作对象的工具（tools）。所有工具的注册入口位于 src/excel_mcp/server.py，该模块通过 FastMCP 实例统一注册，并使用 ToolAnnotations 为每个工具打上 destructiveHint / readOnlyHint 等元数据以帮助大模型理解其副作用（资料来源：src/excel_mcp/server.py）。

按 manifest.json 的 tools 列表，server 暴露了约 20+ 个工具，覆盖工作簿（workbook）、工作表（worksheet）、数据读写、公式、格式化、图表、数据透视表、Excel 原生表（Table）以及行列增删等功能。整体调用流程如下：

flowchart LR
    A[MCP Client<br/>Claude/Ontheia] -->|JSON-RPC| B[FastMCP<br/>server.py]
    B --> C[Validation Layer<br/>validation.py]
    C --> D[Domain Modules<br/>workbook / sheet /<br/>data / calculations /<br/>formatting / chart / pivot / tables]
    D --> E[(openpyxl<br/>xlsx files)]

工具分类与职责

工作簿与工作表管理

工作簿级别的操作集中在 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 提供实现（资料来源：src/excel_mcp/sheet.py）。这些工具在 TOOLS.md 中均以 filepath、sheet_name、start_cell / end_cell 等统一参数风格暴露给 LLM。

数据读写

read_data_from_excel 与 write_data_to_excel 是最常用的两个数据交互工具，二者签名（如 start_cell 默认 "A1"）定义在 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 注册到 MCP 端点。底层实现在 src/excel_mcp/calculations.py 中：函数会先调用 validate_cell_reference，再通过 validate_formula 做语法与安全检查，最后由 openpyxl 写入并 wb.save() 落盘（资料来源：src/excel_mcp/calculations.py）。

公式安全校验

由于公式注入是社区关注的高危面，校验逻辑被独立抽取至 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 实现，覆盖字体、边框、底纹、对齐、条件格式、保护属性等，并支持在同一次调用中合并单元格（资料来源：src/excel_mcp/formatting.py）。create_chart 通过 create_chart_in_sheet 暴露，支持 line/bar/pie/scatter 等类型；create_pivot_table 由 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 定义了 ValidationError、WorkbookError、SheetError、DataError、FormattingError、CalculationError、PivotError、ChartError 等领域异常。工具函数通常将已知业务异常以 f"Error: {str(e)}" 形式直接返回给调用方，而将意外异常透传给上层日志（资料来源：src/excel_mcp/server.py）。

已知限制与社区关注

虽然 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 参数，需对齐依赖版本。

工具速查表

参见

• README.md — 项目总览与传输方式（stdio / SSE / streamable-HTTP）
• manifest.json — MCPB 安装清单与声明的工具列表
• GitHub Issues · haris-musa/excel-mcp-server — 安全审计、客户端兼容性与版本兼容性问题汇总

传输协议概览

服务器实现三种 MCP 传输方式：stdio、SSE（已弃用）以及 streamable-HTTP，可在启动时通过命令行参数切换 README.md:33-38。stdio 是 Claude Desktop、Cursor 等本地客户端的默认通道，启动后通过标准输入输出交换 JSON-RPC 消息，无需额外网络监听 manifest.json:17-22。

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。例如：

@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：

{
  "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。

部署安全注意事项

服务器暴露约 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

安全、验证与操作

概述

excel-mcp-server 是一个基于 Model Context Protocol（MCP）的 Excel 文件操作服务器，可在不安装 Microsoft Excel 的前提下让 AI 代理创建、读取与修改工作簿。围绕"安全、验证与操作"这一主题，服务器在 MCP 工具层（src/excel_mcp/server.py）、业务逻辑层（src/excel_mcp/validation.py、src/excel_mcp/calculations.py）与数据验证层（src/excel_mcp/cell_validation.py）共同提供输入校验、异常捕获与可观察能力。运行时通过 stdio、SSE（已弃用）和 streamable-HTTP 三种传输方式对外暴露（资料来源：README.md:23-39）。

输入验证机制

服务器对三类关键输入进行验证：公式、单元格引用与范围边界。

公式验证：validate_formula 函数通过正则提取公式内的函数名，并与黑名单比对。黑名单中包含以下被认为不安全的函数：

apply_formula 工具强制公式以 = 开头，并在写入前调用 validate_formula_in_cell_operation 二次校验单元格引用与公式语法（资料来源：src/excel_mcp/calculations.py:18-44）。

范围与引用验证：validate_range_bounds 检查起止行列是否落在工作表 max_row / max_column 范围内（资料来源：src/excel_mcp/validation.py:60-90）；validate_formula_in_cell_operation 使用 re.findall(r'[A-Z]+[0-9]+(?::[A-Z]+[0-9]+)?', formula) 提取公式中的所有单元格与范围引用并逐个校验（资料来源：src/excel_mcp/validation.py:38-58）。

数据验证元数据：读取数据时，read_data_from_excel 可附带每个单元格的数据验证信息，包含验证类型、操作符、下拉列表允许值、公式约束、提示与错误信息（src/excel_mcp/cell_validation.py）。

安全风险与社区共识

v0.1.8 修复了 SSE/streamable-HTTP 传输层的路径遍历漏洞（release notes），但社区安全审计仍指出若干待解决问题：

• 任意文件路径访问：create_workbook 与约 20 个写入工具接受未净化的文件路径，可能写入预期外的位置（Issue #120、#128）。
• 公式注入绕过：write_data_to_excel 不复用 apply_formula 的公式黑名单校验，攻击者可借助 data 列表写入以 = 开头的危险公式（Issue #134）。
• 缺乏用户标识与策略强制：stdio 模式下服务器对本地文件系统拥有完全写权限，且无法区分不同 MCP 客户端用户，缺少写操作的策略强制（Issue #138、#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）。

异常体系分为 ValidationError、WorkbookError、SheetError、DataError、FormattingError、CalculationError、PivotError、ChartError，各业务模块抛出后由 MCP 装饰器统一捕获并返回 "Error: ..." 字符串，使 LLM 能够解析失败原因（资料来源：src/excel_mcp/server.py:1-30）。

工具总数与分类在 manifest.json 中静态声明，涵盖工作簿、工作表、数据、公式、图表、数据透视表、表格与行/列操作。完整签名详见 TOOLS.md。

参见

• README.md — 传输方式与启动说明
• TOOLS.md — 工具完整签名清单
• Issues #120、#128、#131、#134、#138 — 安全审计与策略强制讨论
• release v0.1.8 — 路径遍历漏洞修复

Pitfall Log / 踩坑日志

项目：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