office-addin-mcp

office-addin-mcp

通过一个使用 Go 编写的二进制程序，让任何 MCP 客户端都能驱动 Excel、Word、Outlook、PowerPoint 和 OneNote 加载项；该程序通过标准输入输出使用模型上下文协议进行通信。

office-addin-mcp 会连接到 Office 用于托管 Office.js 加载项的 WebView2 运行时，然后向大模型客户端提供一套高级工具接口。服务器为每个工作流提供一次工具调用，而不是让模型学习如何串联 15 个原始 Office.js 基本操作。

参见最新版本 · CHANGELOG.md · PLAN-workflow-surface.md。

亮点

• 工作流工具，而非基本操作。 excel.tabulateRegion、word.applyEdits、outlook.draftReply、powerpoint.rebuildSlideFromOutline、onenote.appendToPage 和 excel.summarizeWorkbook，每个工具都将过去需要 5–20 次调用的操作压缩为一次 Office.js 批处理（一次 CDP 往返）。
• 服务端查询 DSL。 excel.query / outlook.query / powerpoint.query / onenote.query 会在宿主内部执行 filter / project / groupBy / agg / limit，因此 10 万行的工作簿也能返回 5 行答案。
• 持久化文档上下文缓存。 *.discover 工具会将工作簿 / 文档 / 邮箱 / 演示文稿 / 笔记本的结构快照保存到 %LOCALAPPDATA%\office-addin-mcp\doccache.json，因此重复的发现调用无需任何 CDP 往返。
• 支持实时订阅的 MCP 资源。 通过 URI 引用 Office 状态 — office://excel/Book1/Sheet1!A1:D20、office://word/<doc>/bookmark/<name>、office://outlook/inbox、office://pp/<deck>/slide<N>、office://onenote/<notebook>/<section>/<page> — 并在内容变更时订阅 notifications/resources/updated。
• 宏录制与回放。 macro.record_start → 运行任意工具序列 → macro.record_stop 会将 JSON 宏写入磁盘。服务器下次启动时，会将每个宏注册为可调用的 macro.<name> 工具。
• Office.js 错误自动诊断。 ItemNotFound、地址解析失败、幻灯片索引错误，以及撰写与读取模式不匹配等问题，都会在失败信息中补充 available_sheets、nearest_name_suggestions、parsed_address、slide_count、item_mode 和 recoveryHint，让模型无需第二次往返即可自行纠正。
• CDP 连接自动修复。 如果 Excel 意外关闭，服务器会在下一次工具调用时检测到连接已断开，停止过时的旁加载注册，重新启动 Excel（必要时也会启动开发服务器），重置会话池，并重试原始操作 — 无需 Agent 介入。仅当服务器负责启动时才会启用（通过 --launch-addin 或先前的 addin.launch 调用）；连接到外部 --browser-url 端点时不会受到影响。
• 长时间操作的进度通知。 addin.launch、addin.ensureRunning 和宏回放会在每个阶段边界（开发服务器启动、旁加载、等待 CDP 就绪、步骤执行）推送 MCP $/progress 通知，让客户端可以显示实时状态栏，而非静止的加载指示器。
• 跨宿主编排。 office.embed 可在一次调用中从 Excel 读取一个区域，并将其插入 PowerPoint 幻灯片。
• 页面自动化备用方案。 page.* / pages.* / inspect.* / interact.* 支持截图、快照、点击、填充、输入、悬停、导航、执行、等待、控制台日志和网络日志 — 在 macOS/Linux 上针对无头 Chrome 使用相同的基本操作。
• 各宿主的 runScript 备用接口。 当工作流工具接口无法满足需求时，excel.runScript、word.runScript、outlook.runScript、powerpoint.runScript、onenote.runScript 可运行任意 <Host>.run 回调。

要求

安装

npm（推荐）

npm install -g @dsbissett/office-addin-mcp

也可以按需运行，无需安装：

npx @dsbissett/office-addin-mcp@latest --help

预构建的 Windows x64、macOS（Intel + Apple Silicon）和 Linux（x64 + ARM64）二进制文件通过可选的 npm 依赖包提供 — 系统会自动获取正确的二进制文件。

从源代码构建

go install github.com/dsbissett/office-addin-mcp/cmd/office-addin-mcp@latest

在 Claude Code 中使用

一条命令即可全局注册此服务：

claude mcp add office-addin-mcp -- npx -y @dsbissett/office-addin-mcp@latest

也可以手动添加。项目级作用域（仓库中的 .claude/mcp.json）或用户级作用域（~/.claude.json → mcpServers）均可：

{
  "mcpServers": {
    "office-addin-mcp": {
      "command": "npx",
      "args": ["-y", "@dsbissett/office-addin-mcp@latest"]
    }
  }
}

然后，在任意 Claude Code 会话中：

1. 打开 Office 宿主（参见下方的 Office 宿主设置），以便 WebView2 调试端口处于监听状态。
2. 让 Claude 执行某项任务 — 例如 “总结此工作簿，然后按区域透视 Sales 工作表。” 它会自动选择 excel.summarizeWorkbook 和 excel.query。
3. 在 Claude Code 中运行 /mcp 查看工具列表，或在 shell 中运行 claude mcp list。

**提示：**传入 --launch-addin，Claude 就能自动加载当前工作目录下的加载项项目。无需手动设置环境变量。

在其他 MCP 客户端中使用

{
  "servers": {
    "office-addin-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@dsbissett/office-addin-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "office-addin-mcp": {
      "command": "npx",
      "args": ["-y", "@dsbissett/office-addin-mcp@latest"]
    }
  }
}

[mcp_servers.office-addin-mcp]
command = "npx"
args = ["-y", "@dsbissett/office-addin-mcp@latest"]

{
  "mcpServers": {
    "office-addin-mcp": {
      "command": "npx",
      "args": ["-y", "@dsbissett/office-addin-mcp@latest"]
    }
  }
}

Office 宿主设置

只有在启动时设置调试端口环境变量，Office 宿主才会通过 CDP 暴露其 WebView2 运行时。此变量由所有 Office 应用共享，因此以下相同设置适用于全部五个应用：

PowerShell

$env:WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS = "--remote-debugging-port=9222"
Start-Process excel.exe my-workbook.xlsx
# or:  Start-Process winword.exe my-document.docx
# or:  Start-Process outlook.exe
# or:  Start-Process powerpnt.exe my-deck.pptx
# or:  Start-Process onenote.exe

命令提示符

set WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=9222
excel.exe my-workbook.xlsx

服务默认会探测 http://127.0.0.1:9222。可通过 --browser-url 或 --ws-endpoint 覆盖。也可以完全跳过设置，使用 --launch-addin — 服务会检测 cwd 下的 Office 加载项项目，并通过 office-addin-debugging 旁加载它。

工具概览

PLAN-workflow-surface.md 的阶段 0 删除了原始的 cdp.* 工具集；以下所有内容都是面向工作流的替代方案。每个工作流工具都对应一次 MCP 调用 → 一次 Office.js 批处理 → 一次 CDP 往返。

Excel

Word

Outlook

PowerPoint

OneNote

跨主机与宏

加载项生命周期与通用页面自动化

MCP 资源

大模型客户端可以通过 URI 引用 Office 状态，而不必在每轮重新获取。启动时会注册五个资源模板：

资源支持 resources/subscribe。服务每 30s 轮询一次指纹，并在内容发生变化时发出 notifications/resources/updated；调用 resources/unsubscribe（或客户端断开连接）会终止轮询 goroutine。

性能说明

• urlPattern 根据目标 URL 的子字符串匹配来选择 WebView2 页面。对某个会话进行首次调用后，选择器缓存会将后续调用中的 diagnostics.cdpRoundTrips 从约 3 降至 1。
• 会话池允许在 60 秒窗口内重新连接 3 次。用尽次数后会显示为 connection/session_acquire_failed。如果服务负责启动，显示该错误前会尝试自动停止并重新启动一次，因此 Excel 的临时重启对 Agent 不可见。
• DocCache 快照通过原子重命名写入，模式为 0600。使用 --no-doccache 可禁用。

标志和环境变量

该二进制不接受位置子命令——它通过 stdio 使用 MCP。旧版 call / daemon / serve --stdio 子命令已移除。

目录结构

cmd/office-addin-mcp/   main entry
internal/tools/         registry, dispatcher, envelope, diagnostics
internal/cdp/           hand-rolled CDP WebSocket client
internal/webview2/      endpoint discovery
internal/session/       session pool + reconnect budget
internal/officejs/      Office.js executor + payloads
internal/js/            embedded Office.js scripts
internal/doccache/      persistent document discovery cache
internal/resources/     office:// URI parsing + provider + polling watcher
internal/recorder/      macro recorder store
internal/tools/macrotool/  macro.record_start / record_stop / replay
internal/mcp/           SDK server wiring + resource registration

许可证

MIT