ExcelAI · MCP 接入手册

为什么必须由插件来起服务端：MCP 是「客户端主动连服务端」。 Codex / WorkBuddy 是客户端，而插件寄生在 Excel 里、本来没有端口，谁也连不进来。 所以插件在进程内起了一个回环 HTTP 服务，客户端连它，它再转发给 Excel。

服务端能力只声明 tools（不提供 resources / prompts），协议版本 2025-06-18。

① 打开设置

Excel 里点 Ribbon 上的 设置 按钮（或插件设置入口），滚动到 「MCP 服务」 分区。

② 打开总开关

勾选 「允许外部 AI 工具连接并操作当前 Excel」。

③ 记下连接地址

开关打开并 保存 后，分区里会显示：

• 一个状态点 —— 🟢 正在监听 127.0.0.1:8931 表示已经在跑；🔴 未运行 多数是端口被占用，换个端口再保存即可。
• 客户端连接地址 —— 形如下面这样，点「复制」拿到它：

http://127.0.0.1:8931/mcp/<你的令牌>

上面 8931 是端口，<你的令牌> 是 32 位十六进制随机串。 它生成一次就固定保存在本机（%LOCALAPPDATA%\ExcelAI\mcp-token.txt），重启 Excel 也不会变 —— 客户端配置一次即可长期用。

还是建议点「复制」拿，别手打：32 位字符打错一位，表现是「地址看着对、就是连不上」，很难查。 地址框下面那行会写明令牌有没有固定住。想换令牌时，点旁边的「重置令牌」（需连点两次确认）。

关于端口

• 默认 8931，可在 1024–65535 之间改。
• 仅监听 127.0.0.1，不对局域网开放。
• 端口被占用时服务会启动失败（状态点亮红），换个端口重存即可 —— 不会崩。

随时开关

• 关掉总开关 → 端口立即停止监听（不是「还监听着但拦请求」），连 TCP 握手都建立不了，这是能给出的最强保证。
• 改完设置 保存即生效，不需要重启 Excel。
• Excel / 插件退出时自动停止。

Codex 把 MCP 配置存在 ~/.codex/config.toml（项目级可用 .codex/config.toml）。在文件末尾加上：

[mcp_servers.excel]
url = "http://127.0.0.1:8931/mcp/<你的令牌>"

把 url 换成你在 3 复制到的那串即可。不需要 bearer_token_env_var 或 http_headers —— 令牌已经在 URL 路径里了。

几个可选项（按需加）：

[mcp_servers.excel]
url = "http://127.0.0.1:8931/mcp/<你的令牌>"
startup_timeout_sec = 20          # 启动超时，默认 10
tool_timeout_sec = 120            # 工具超时，默认 60 —— 跑大表建议调大
default_tools_approval_mode = "auto"   # 免审批（本服务已是免确认语义）

WorkBuddy 走 连接器 入口：

1. 打开 连接器管理 页面。
2. 找到右上角的 自定义连接器 入口（或「添加 MCP 服务」）。
3. 填名称 + 类型选 HTTP / URL，把 3 复制的地址贴进 URL。
4. 保存后按提示点「信任」启用。

多数客户端用 mcpServers 这一段 JSON：

{
  "mcpServers": {
    "excel": {
      "type": "http",
      "url": "http://127.0.0.1:8931/mcp/<你的令牌>"
    }
  }
}

要点：

• 不要填 command / args —— 那是 STDIO 用的，本服务是 HTTP。
• 不带 Authorization 头，令牌在 URL 里。
• 有的客户端把 type 写作 "streamable-http" 或 "sse"，按客户端要求填。

好的开场是让 AI 先看：

用 excel 工具看一下当前工作簿有哪些表、各多少行。

它会调 get_workbook_summary / get_sheet_profile / inspect_current_data。 之后你说「把 B 列的空值填成上一行的值」这类话，它才知道该动哪儿。

• 改之前先让它「看一眼」：AI 看不见你的屏幕，只能通过工具读。 让它先 get_range_preview 或 get_sheet_profile，比上来就写要靠谱得多。
• 大改动前先自己备份，或者让它先 preview_write_range 看差异。 免确认意味着没有「要不要覆盖」这一问。

服务端一共暴露 85 个工具。工具表和对话框里的 AI 用的是同一份定义 （都来自 ToolCallHandler.GetToolDefinitions），所以能力与插件本体基本一致 —— 不是另起一套，MCP 只是把同一张表换了个协议发出去（另有两处刻意的删减，见 7.0）。

① batch_process_workbooks —— 列不出来，因为调不动

它（批量合并文件夹内的 Excel）不在 MCP 工具表里，但在对话框里能用。

原因：它挂在对话框的编排层执行（WebChatControl.xaml.vb 里 Await HandleBatchProcessAsync）， 因为要弹一个文件夹选择框让用户选目录。MCP 走的是同步分发链（McpBridge.InvokeTool → ExecuteToolCall）， 到不了那里，硬调只会得到「未知工具」。

② OfficeCLI 一族 —— 能调，但 MCP 不提供

officecli_* 那 16 个工具也不在 MCP 工具表里，但它们在对话框里能用。

这不是因为「它们坏了」，而是语义不是一回事：MCP 服务的作用域是「操作当前正在运行的这个 Excel」， 而 OfficeCLI 是外部进程去读写磁盘上的文件。混在同一张工具表里，外部 AI 会挑到它去改用户没打算改的文件。

两道门都是关着的，防的不是同一件事：

• 工具表不列它们（GetToolDefinitions 的 mcpReachableOnly 分支里整族摘掉）；
• 执行侧再拦一道（McpBridge.InvokeTool 里在碰 COM 之前就拒）—— 客户端会缓存 tools/list，模型也可能凭上一轮记忆直接调，只靠不列挡不住。

读写磁盘上别的 Office 文件（不是当前工作簿）：

officecli_get_status、officecli_get_capabilities、officecli_get_schema、 officecli_inspect_file、officecli_validate_file、officecli_query_file、 officecli_get_element、officecli_modify_copy、officecli_batch_modify_copies、 officecli_batch_modify_selected、officecli_create_presentation、 officecli_get_selected_files、officecli_run_command、officecli_batch、 officecli_watch_preview、officecli_unwatch_preview。

服务做了三重防护：

• 只绑 127.0.0.1 —— 非回环地址的请求一律 403，不对局域网开放。
• 校验 Origin 头 —— 拦截恶意网页的跨站请求（DNS rebinding）。没有 Origin 的原生客户端正常放行。
• 路径随机令牌 + 定长比较 —— 令牌不对一律回 404（不回 401，不告诉扫描者这儿有个服务）。

另外：

• 总开关关闭 = 端口真的不监听。
• 每个请求都记一笔（最近 20 条），设置页可以看「最近发生了什么」。
• 令牌固定保存在本机（%LOCALAPPDATA%\ExcelAI\mcp-token.txt）—— 重启 Excel 不会变，客户端配置长期有效。只有在设置页点过「重置令牌」之后旧地址才会作废，届时回设置页重新复制即可。