excel-sovereign-mcp

本地 Excel MCP。模型只提交工作和路径，服务端决定用文件包还是真正的 Excel，保存一次，并在返回前截图。

Windows · Python 3.11+ · 需要本机 Microsoft Excel 做重算和截图 · MIT

纯包写入可以不经过 Excel 完成修改。只要这次调用要重算、改结构、碰到透视或查询，或者要截图核对，就会打开 Excel。它不是云服务，工作簿不出本机。

安装

git clone https://github.com/limoaCatherine/excel-sovereign-mcp.git
cd excel-sovereign-mcp
python -m pip install -e .
dotnet build vendor\mcp-server-excel\src\ExcelMcp.CLI\ExcelMcp.CLI.csproj -c Release

dotnet build 需要 .NET 10 SDK。编出的 excelcli.exe 留在本机构建目录，不进版本库。已经编过也可以用环境变量 EXCELCLI 指向它。找不到时，服务会到上面的构建目录里找。

用 Cursor 打开本仓库时，.cursor/mcp.json 会注册名为 excelMCP 的服务。它运行 scripts/serve.py。这个脚本按自己的位置把 src 放进模块路径，并固定走 stdio。

不要只把命令写成 excel-sovereign-mcp。那个入口在 pip install -e . 之后落在 Python 的 Scripts 目录。Cursor 从开始菜单启动时，这个目录经常不在 PATH 里。进程一起就退出，重启后工具列表是空的。

在别的窗口里也要用时，写到用户级 mcp.json，路径用绝对路径：

{
  "mcpServers": {
    "excelMCP": {
      "type": "stdio",
      "command": "C:\\Path\\to\\python.exe",
      "args": ["C:\\Path\\to\\excel-sovereign-mcp\\scripts\\serve.py"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

type 要写 stdio。同一台机器上用户级配置和本仓库配置会各出现一条 excelMCP。在本仓库里用项目这一条，在其他窗口里用用户级这一条。

调用前先在 Excel 里保存并关闭同一个文件。公式用英文函数名。数字格式用 Excel 格式码。

Related MCP server: Excel MCP Server

架构

六个入口，一条写入管道。模型不传 engine，也不持有 session_id。入口只决定这批 ops 属于哪一组动作，不决定用文件包还是 Excel。

flowchart TD
  model[模型] --> read[workbook_read]
  model --> apply[workbook_apply]
  model --> table[excel_table]
  model --> modeltool[excel_model]
  model --> view[excel_view]
  model --> vba[excel_vba]
  read --> lock[按绝对路径加锁]
  apply --> lock
  table --> lock
  modeltool --> lock
  view --> lock
  vba --> lock
  lock --> inspect[检查 zip 部件和 ops]
  inspect --> route{整批路由}
  route -->|纯包| ox[openpyxl 在内存里改]
  route -->|结构、表、透视、查询、宏或 COM 部件| com[一次 excelcli 会话]
  ox --> save[只保存一次]
  com --> save
  save --> shot[服务端选定范围并截图]
  shot --> back[返回 committed、verified 和图片]

各入口使用同一份 ops 形状。一批里只要有一步需要 Excel，整批都走 COM。表、查询、数据模型和 VBA 分开发送，避免每次对话带上全部参数。这四个入口也可以带上单元格、排版和工作表结构，填数据和建表仍是一次调用。

sequenceDiagram
  participant M as 模型
  participant S as excel-sovereign-mcp
  participant E as Excel
  M->>S: 一个 ops 数组
  S->>S: 锁、检查、路由
  alt 保存前失败
    S-->>M: committed false，文件字节不变
  else 保存成功
    S->>E: 需要时重算，然后截图
    alt 截图失败
      S-->>M: committed true，verified false，只建议 verify
    else 核对通过
      S-->>M: ok true，附带图片
    end
  end

verify 是一个操作，不是第四个工具。它只重新打开、重算和截图，不会把插入或删除再做一遍。

六个入口

动作名写在对应工具的说明里。每个 op 只带自己用到的字段，不把全部命令参数放进工具 schema。送错入口会返回 wrong_tool，并给出该用的工具名。

读的四种 mode：

• overview：每张表的实际数据范围、非空格数、公式数、合并区、冻结和隐藏状态。preview 附带前几行。数据之外还有残留格式时带 extent。

• sparse：只返回非空格，按行分组。普通格是值，公式格是 {f, v}。

• dense：按 set_values 的二维形状返回。整页没有公式时不带 formulas。

• find：在值或公式文本里搜关键字，可限定工作表和区域。

查询动作（*_list、table_read、powerquery_view、datamodel_evaluate、validation_get、comment_get、vba_view）把结果放在 results 里，按这次 ops 的下标对应。整次调用全是查询时不保存、不截图，返回 readOnly: true。

trim_sheet 删掉最后一个非空格之后的行和列，但留下公式、名称、条件格式或数据验证仍在引用的区域。没有可删的行列时不保存，note 说明原因。

单次写入超过 10 万格返回 too_large，不截断保存。只接受 .xlsx 和 .xlsm。.xls、.xlsb、加密和 IRM 在改动前拒绝。

返回

• committed: true 表示文件已经保存。不要把同一批插入、删除、重命名再发一次。

• 已经保存但 verified: false 时，只发送 suggestedNextActions 里的 verify。

• calculated: true 只表示这次已经把重算后的缓存写回文件。只改字体、填充、行高列宽时 calc 为 skipped。

• 纯查询的 committed 是 false，并带 readOnly: true。

和别的 Excel MCP 比

下面只写各自仓库里能对上的事实，不把没测过的速度排成名次。

haris 的改名行为见其 src/excel_mcp/sheet.py。透视实现见其 src/excel_mcp/pivot.py，那里创建的是 openpyxl 的 Table。knorq 的限制写在它自己的 README 里。sbroenne 的 31 个工具和 COM 路径写在它的 README 里。negokaz 的分页默认 4000 格，截图是单独工具。

耗时出在哪里

截图要打开 Excel，所以纯包修改也不会变成一次纯内存返回。

本机各观测一次，时间含截图：

这是一台 Windows 机器上的单次观测，用来说明时间主要花在启动 Excel 和截图，不是四个项目的速度排名。

做表

新表用 layout。profile 只表示起稿习惯，不改变颜色：

• finance：参数、勾稽、清单

• analytics：参数、事实表、清单

• general：游戏、制造或其他行业，按列自选块

事实表会建成 Excel 表，表体不再用 format 刷。录入格蓝字淡底，跨表公式绿色，含 [ 的公式红色。

部署边界

适合装在写表的那台 Windows 上，用 stdio 交给 Cursor 或其他 MCP 客户端。

不提供托管地址，也不把工作簿上传到服务端。Excel 必须能打开桌面。锁屏、没有桌面或截图超时时，已经保存的文件保持 committed: true，再用单独的 verify 补图。

COM 调用串行。不同文件的纯包修改可以并行，读也会等到这把路径锁。锁放在系统临时目录，不放在工作簿旁边。

仓库里有什么

src/excel_sovereign/     服务、锁、路由、openpyxl、excelcli、截图、做表
skills/excel-sovereign/  给模型的调用约定
tests/                   不启动 Excel 的核心测试，以及要 Excel 的验收
vendor/excel-mcp-server/ Haris 的 openpyxl 来源，保留 src 与 LICENSE
vendor/mcp-server-excel/ 编译 excelcli 需要的 src、构建脚本和 LICENSE

两份上游代码保留各自的 LICENSE。视频、大样例、上游测试、站点、扩展和安装包不放进本仓库。本仓库的改动是：excelcli 只有在这次调用允许宏时才把 AutomationSecurity 设为 Low，并增加 range.get-spill 用来量动态数组溢出区。构建产物 bin/ 和 obj/ 不提交。

开发

python -m pytest tests/test_core.py tests/test_layout.py -q
python -m pytest tests/test_acceptance.py -q

验收测试会打开 Excel。详细设计在 开发方案.md。

许可

本仓库自己的代码使用 MIT。vendor/ 中的代码版权属于原作者，同样是 MIT，随各自的 LICENSE 再分发。