sbroenne/mcp-server-excel · 上手攻略

  • 仓库：sbroenne/mcp-server-excel
  • 链接：https://github.com/sbroenne/mcp-server-excel
  • 分类：agent / MCP server（Excel 自动化）
  • 作者：spark
  • 更新：2026-10-04

⚠️ 数据来源声明：本攻略基于 README.md（2026-10-04 fetch · 200 OK）、FEATURES.md、官方站点 excelmcpserver.dev/installation/、SkillsLLM 安全报告及仓库 metadata。所有命令、版本号均经官方页面核验；如无独立三方核对处，会在文中标注「官方自述」。

⚠️ 操作数偏差：仓库卡片显示「326 operations」，README 与 FEATURES.md 显示「387 operations / 31 tools」。本文以官方 README 为准（387/31），卡片数字疑似旧版本快照，建议以 GitHub Releases 当前版本号为准。

一、这是什么 / 解决什么问题

mcp-server-excel（对外品牌 ExcelMcp）是一个把真实的 Microsoft Excel 桌面应用接给 AI Agent 的桥接层。它提供两种入口：

  • MCP Server：让 GitHub Copilot、Claude Desktop、Cursor、Windsurf、Codex CLI 等 MCP 客户端直接用自然语言操作 Excel；
  • CLI（excelcli）：面向 coding agent / CI-CD / RPA，token 占用远低于 MCP，适合脚本化批量执行。

它和市面上其他"Excel MCP"最本质的区别：不是文件解析器，而是通过 Excel 官方 COM API 驱动真实的 Excel.exe。这意味着 Power Query 刷新、公式重算、DAX 评估、VBA 与 =PY() 执行、数据透视表 / 图表 / 数据模型 / 宏 / 工作簿格式都能完整保留——你可以在自动化过程中打开 Excel 实时看 AI 在做什么。

核心问题域（官方四档归类）： 1. Data & Analytics：Power Query（M）、Power Pivot、DAX、Excel Tables、PivotTables、数据连接； 2. Cells & Workbooks：范围、公式、格式、工作表、文件、计算、命名区域； 3. Charts & Visuals：图表、切片器、条件格式、截图、绘图、迷你图； 4. Automation & Advanced：VBA、Python in Excel（=PY()）、Goal Seek、Scenarios、数据表、窗口、XML Maps。

官方自述：「31 tools with 387 operations」覆盖端到端 Excel 自动化。

二、快速安装

强前置（README 明确）： - 操作系统：Windows（macOS / Linux 不支持） - Microsoft Excel 2016 或更新版本（桌面版，不能是 365 在线版） - 交互式桌面（即 Excel.exe 要能正常打开 UI；不适合无头服务器 / CI 容器） - 自动化过程中Excel 必须独占访问目标工作簿——先关闭再启动

按使用场景分三档：

场景 推荐入口 一行命令 / 步骤
VS Code + GitHub Copilot VS Code 插件 在 VS Code Marketplace 安装 sbroenne.excel-mcp（官方自述已 8,468+ 安装）
Claude Desktop / Cursor / Windsurf / 其他 MCP 客户端 MCPB / npx npx -y @sbroenne/mcp-server-excel@latest
Coding agent / 脚本 / CI CLI npx -y @sbroenne/excelcli@latest，或 npm i -g @sbroenne/excelcli 取得 PATH 命令
完全不想用 npm 独立 ZIP 从 GitHub Releases 下载 excel-skills-v{version}.zip，手工替换可执行文件

Claude Desktop / 其他 MCP 客户端的 MCP 配置片段（官方文档示例）：

{
  "mcpServers": {
    "excel": {
      "command": "npx",
      "args": ["-y", "@sbroenne/mcp-server-excel@latest"]
    }
  }
}

⚠️ @latest 在启动时解析，遵循 npm 普通缓存策略；它不会自动升级已经在跑的 server / CLI 后台服务，升级后需手动重启 MCP 客户端。

可选：报告格式化技能（cross-platform）——若你需要 AI 输出带排版的 Excel 报告，可再装 skills 插件：

# CLI 报告排版技能
npx skills add sbroenne/mcp-server-excel-plugins --skill excel-cli-report-formatting

# MCP 报告排版技能
npx skills add sbroenne/mcp-server-excel-plugins --skill excel-mcp-report-formatting

# 交互式（让你选装哪个）
npx skills add sbroenne/mcp-server-excel-plugins

# 给指定 agent（Claude Code / Cursor / Copilot … 共 43+ 家）
npx skills add sbroenne/mcp-server-excel-plugins --skill excel-cli-report-formatting -a claude-code

三、核心用法

下面命令均可在 PowerShell / cmd / Windows Terminal 直接运行，依赖前提是 Excel 已装好并关闭目标工作簿。

3.1 用 MCP Server（在 Claude Desktop / Cursor 里直接说人话）

启动 MCP 后，你只需要对 AI 说：

  • 「用 Power Query 把 products.csv 导入，并加载到 Data Model。」
  • 「基于当前数据建一个按地区汇总营收的 PivotTable，再加个柱状图。」
  • 「用 Goal Seek 找出达成 $100,000 利润所需的价格。」
  • 「过程中把 Excel 窗口显示出来（'Show me Excel while you work'）。」

MCP Server 走进程内调用 ExcelMcp Core；适合对话式探索、富 schema 工具发现、持久会话。

3.2 用 CLI（脚本化与 CI）

CLI 走后台守护进程——一次启动后工作簿会话跨命令延续，最适合批量 / 自动化 / coding agent。

# 看顶层命令
excelcli --help

# 看具体命令的参数
excelcli <command> --help
# 例：
excelcli pivot-table --help
excelcli refresh-power-query --help
excelcli run-vba --help

CLI 把所有 387 项操作压缩成单一工具面给 coding agent，token 占用远低于 31 个独立 MCP tool（官方 README 对比表原话：「One compact tool surface and substantially lower token usage」）。

3.3 用 VS Code 插件（最省事）

在 VS Code 装好 sbroenne.excel-mcp 后，Copilot Chat 里直接说需求即可。插件自带 server，但不含 CLI——脚本场景需要再单独装一次 CLI。

排查入口：VS Code 输出面板 → 选择 ExcelMcp / excel-mcp 通道，可看启动日志。

3.4 一个最小工作流（MCP 视角）

  1. excel_list_files / excel_list_sheets 探查目标工作簿结构；
  2. excel_power_query_refresh 刷新外部数据源；
  3. excel_pivot_create 建 PivotTable；
  4. excel_chart_create 配 PivotChart；
  5. excel_screenshot 抓图做报告嵌入。

精确命令名请以你客户端里 MCP tool 列表为准；CLI 端以 excelcli <command> --help 为准。本文不复刻逐条 schema，避免随版本漂移。

四、典型适用场景

  • 财务 / 运营月报自动化：从 ERP 导出 CSV → Power Query 入 Data Model → DAX 量度 → PivotTable + 图表 → VBA 生成 PDF。AI 全程对话驱动。
  • 数据分析 Agent 的"真 Excel"工作流：研究员让 Claude / GPT 直接改活工作簿、跑 Goal Seek、试 What-if，保留原格式与宏。
  • CI / CD 中的报表对账：用 excelcli 调度刷新 + 校验 + 归档，token 比 MCP 省一截。
  • Power Platform 协同：Power Query + Power Pivot + DAX 全链路在 Excel 内闭环，不需要中间数据导出。
  • 报告排版 AI 插件：装 excel-cli-report-formatting / excel-mcp-report-formatting 后，让 AI 直接按预设模板出可读报告。

五、坑与注意

每坑配"现象 / 影响 / 修复"三段式，对齐 W39/W40 lessons §八 工程节要求。

  1. 平台限定被忽略 - 现象：在 macOS / Linux / WSL 上跑 npx @sbroenne/excelcli@latest，报 COM / 注册类错误或静默无输出。 - 影响：所有依赖桌面 Excel COM 的能力全部失效，README 顶上红框已明示「Windows only」。 - 修复：换 Windows 主机；或在 Windows VM / RDP 跳板里运行；远程容器方案行不通（必须交互式桌面）。

  2. 工作簿未独占 - 现象：Excel 已经在 UI 里打开了目标 .xlsx，启动 MCP / CLI 时报"文件被锁定"或写入失败。 - 影响：写入冲突、数据丢失、Power Query 中途挂起。 - 修复：调用前先关闭所有 Excel 窗口；或让 agent 先 excel_close_workbook 强关。

  3. @latest 不会热升级运行中的服务 - 现象：升级 npm 包后，老 MCP server 进程仍跑旧版本，行为不一致。 - 影响：跨会话结果漂移，新 tool schema 不可见。 - 修复：升级后手动重启 MCP 客户端（Claude Desktop / Cursor / VS Code）。

  4. Excel 版本/许可差异导致部分能力不可用 - 现象：某些 Power Pivot / Python in Excel / DAX 高级功能报"未授权"。 - 影响：Data Model 相关命令不可用；=PY() 仅在 Microsoft 365 配 Python 的版本里能跑。 - 修复：核对 Excel 版本与账号授权（FEATURES.md 提到「Excel 版本、账号许可、数据驱动、交互式桌面均影响能力可用性」）。

  5. Skills 插件命名空间混淆 - 现象：用 npx skills add sbroenne/mcp-server-excel --skill excel-cli 装完，老的 excel-mcp / excel-cli 广技能仍残留。 - 影响：新旧技能并行，可能被 agent 误调到旧入口。 - 修复：用客户端的 skill 管理器显式移除旧技能；新插件名是 excel-cli-report-formatting / excel-mcp-report-formatting，范围更窄、专做报告排版。

  6. 无头 / 服务端批处理期望 - 现象：试图在 GitHub Actions / Azure DevOps 容器里跑 excelcli 做报表。 - 影响：必须交互式桌面 → 容器里 Excel 弹不出 UI，COM 调用挂死。 - 修复：把 Excel 自动化放到带桌面会话的 runner（如自托管 Windows agent + AlwaysOn RDP session）；CI 只触发、不内嵌运行。

  7. 跨设备同步工作簿的格式丢失 - 现象：OneDrive / SharePoint 同步盘上的工作簿经 ExcelMcp 改写后，偶发图表 / 数据透视表缓存异常。 - 影响：可视化层异常，公式与数据完好。 - 修复：把工作簿放本地 NTFS 路径；或运行完先 Save As 重写文件再回同步盘。

六、与同类对比

工具 驱动方式 平台 适用差异 入口形态
sbroenne/mcp-server-excel（本文） 真 Excel COM Windows only 保留宏 / Power Query / DAX / PivotTables / Data Model / 格式；MCP + CLI 双入口；387 操作
negokaz/excel-mcp-server（npm：@negokaz/excel-mcp-server） 文件级读写 Windows 优先，其他平台 fallback 适合跨平台读 .xlsx、读写单元格 / 公式 / 新建 sheet；不保留宏 / 数据模型 / 实时计算
Office 官方 Microsoft 365 MCP（Microsoft 自家） Graph API 云端 不操作本地 Excel；多用于跨端协作与 Microsoft 365 内容
xlwings（Python 库） COM 调用 Excel Windows / macOS（受限） 偏向 Python 自动化，AI 需配 code-execution 沙箱；非 MCP 原生
openpyxl / xlsxwriter（Python 库） 纯文件解析 全平台 不调用 Excel，Power Query / 公式需手动重算；适合生成静态报表
pywin32 + 手搓 MCP 包装 COM 直调 Windows 最大灵活，但需自行实现 tool schema 与持久化

一句话定位差异：sbroenne 的强项是让 AI 操作活的 Excel，而不是让 AI 读写 .xlsx 文件。如果你需要 Power Query / 宏 / Data Model / 实时看到 Excel 在改，选它；如果你只是跨平台读写单元格，选 negokaz/excel-mcp-server；如果你要云端协作，选 Microsoft 官方 Graph API MCP。

七、一句话推荐结论

需要 AI 操作真实 Excel（Power Query / DAX / 宏 / 数据透视表 / Data Model 都要保留），用户跑 Windows + 桌面 Excel 且愿意关闭工作簿让 AI 独占——直接装 sbroenne.excel-mcp VS Code 插件或 npx @sbroenne/mcp-server-excel@latest；脚本 / CI 场景加装 @sbroenne/excelcli。其他平台或纯文件读写需求，请选 negokaz/excel-mcp-server 或 openpyxl。

spark · 2026-10-04 · 来源：README.md (sbroenne/mcp-server-excel@main) · excelmcpserver.dev/installation/ · FEATURES.md · SkillsLLM 安全报告 · VS Code Marketplace 页面