excel-mcp

excel-mcp

让你的 AI Agent 读取真实、杂乱的 Excel 文件。 一个 MCP 服务， 可以处理大模型难以应对的情况：多个工作表、位于实际表格上方的标题行，以及 合并单元格。

如果你把电子表格粘贴到提示词中，模型就得猜测数据从哪里开始，以及合并单元格是什么意思，而且 经常会猜错。这个服务会用确定性代码正确读取文件，因此数值准确，模型也不会编造单元格内容。

它解决的问题

真实的电子表格几乎从不会在 A1 单元格处整齐地开始：

A1:  Quarterly Sales Report 2024      <- title, not data
A2:  Generated by finance             <- note, not data
A3:  (blank)
A4:  Region | Product | Units         <- the actual header
A5:  North  | Widget  | 120
...

让大模型读取这样的表格，它往往会把标题当作列名。read_table 会自动检测表头位于第 4 行，并返回整洁的记录。合并单元格（一个值跨越多行）会向下填充，因此行不会丢失所属类别。

它提供给 Agent 的工具

工具	功能
list_sheets(path)	工作簿中的所有工作表及其大小
preview_sheet(path, sheet, rows)	以网格形式显示顶部行，方便 Agent 查看布局
read_table(path, sheet)	将实际数据表作为记录返回。还会报告可能出错的判断：header_source（显式指定／自动检测）、header_confidence 和 forward_filled_columns（从合并单元格推断出的值，而非实际读取的值）
sheet_to_csv(path, sheet)	将表格转换为整洁的 CSV 文本

开始使用（Claude Desktop）

最快的使用方式是通过 Claude Desktop 这样的 MCP 客户端。只需三步：

1. 安装

pip install "excel-agent-mcp[mcp]"

2. 将其添加到客户端配置中

Claude Desktop 的配置文件位于：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

添加服务：

{
  "mcpServers": {
    "excel": { "command": "excel-agent-mcp" }
  }
}

3. 重启 Claude Desktop。 你会看到一个工具图标出现，表示服务已连接。

就这样。现在可以询问机器上的任意 .xlsx 文件：

You:  What's in /Users/me/reports/sales.xlsx?

Agent (calls list_sheets, then read_table):
  The workbook has one sheet, "Q1". The table starts on row 4 (the rows above
  are a title). 3 rows: North/Widget/2400, South/Widget/3000, South/Gadget/2400.
  Total revenue 7800.

Agent 会读取实际文件，而不是猜测，因此数值准确。

限制文件访问： 若要阻止 Agent 读取某个文件夹之外的内容，请设置 EXCEL_MCP_ALLOWED_DIR。请参阅 SECURITY.md。

与其他 MCP 客户端搭配使用

同一个服务可用于任何 MCP 客户端，只是配置有所不同。请将 excel-agent-mcp 用作命令。

Cursor — ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（每个项目）。格式与 Claude Desktop 相同，并且支持热重载（无需重启）：

{ "mcpServers": { "excel": { "command": "excel-agent-mcp" } } }

VS Code / GitHub Copilot — .vscode/mcp.json。请注意键名不同（使用 servers，而非 mcpServers）， 并且必须填写 type。工具仅在 Copilot Agent 模式下运行：

{ "servers": { "excel": { "type": "stdio", "command": "excel-agent-mcp" } } }

Windsurf — ~/.codeium/windsurf/mcp_config.json（若文件不存在，请创建）。格式与 Claude Desktop 相同：

{ "mcpServers": { "excel": { "command": "excel-agent-mcp" } } }

Cline — 在 VS Code 的扩展 MCP 设置面板中添加（命令：excel-agent-mcp）。

理解输出

read_table 不仅会返回数据，还会说明结果的可信度，让你既能信任整洁的解析结果，也能核查猜测：

{
  "columns": ["Region", "Product", "Revenue"],
  "rows": [ ... ],
  "header_row": 3,
  "header_source": "auto-detected",
  "header_confidence": 0.42,
  "forward_filled_columns": ["Region"]
}

• header_source — 如果你指定了表头所在行，则为 "explicit"；如果是自动猜测的，则为 "auto-detected"。
• header_confidence — 自动检测表头时的 0..1 置信度。数值较低表示难以判断； 如果结果看起来不对，请显式传入 header_row。
• looks_clean + table_warnings — 对整个表格的评估（标记表头置信度低、列未命名、表格大部分为空等情况），与下方按列提供的信号相互独立。
• forward_filled_columns — 值来自合并单元格的列。这些值是推断得出的（向下复制以填充区域），而非逐个单元格读取，因此请谨慎看待。

我们的想法是：明确展示可能出错的判断，而不是交出看似整洁、却隐藏了猜测的结果。

也可直接在普通 Python 中使用

from excel_mcp import reader

reader.list_sheets("report.xlsx")
reader.read_table("report.xlsx", "Sales")     # {'columns': [...], 'header_source': ..., ...}
reader.sheet_to_csv("report.xlsx", "Sales")

测试

python -m unittest discover -s tests     # builds its own messy xlsx, runs anywhere

许可证

MIT