office-addin-mcp

Drive Excel, Word, Outlook, PowerPoint, and OneNote add-ins from any MCP client — through one Go binary that speaks the Model Context Protocol over stdio.

office-addin-mcp attaches to the WebView2 runtime that Office uses to host Office.js add-ins, then exposes a high-level tool surface to LLM clients. Instead of teaching the model how to chain 15 raw Office.js primitives, the server ships one tool call per workflow.

See the latest release · CHANGELOG.md · PLAN-workflow-surface.md.

Highlights

• Workflow tools, not primitives. excel.tabulateRegion, word.applyEdits, outlook.draftReply, powerpoint.rebuildSlideFromOutline, onenote.appendToPage, and excel.summarizeWorkbook each compress what used to be 5–20 calls into one Office.js batch (one CDP round-trip).
• Server-side query DSL. excel.query / outlook.query / powerpoint.query / onenote.query run filter / project / groupBy / agg / limit inside the host so a 100k-row workbook returns a 5-row answer.
• Persistent document context cache. *.discover tools snapshot workbook / document / mailbox / deck / notebook structure to %LOCALAPPDATA%\office-addin-mcp\doccache.json so repeat discovery calls cost zero CDP round-trips.
• MCP Resources with live subscriptions. Reference Office state by URI — office://excel/Book1/Sheet1!A1:D20, office://word/<doc>/bookmark/<name>, office://outlook/inbox, office://pp/<deck>/slide<N>, office://onenote/<notebook>/<section>/<page> — and subscribe to notifications/resources/updated when contents change.
• Macro record & replay. macro.record_start → run any sequence of tools → macro.record_stop writes a JSON macro to disk. On next launch the server registers each macro as a callable macro.<name> tool.
• Auto-diagnostics on Office.js errors. ItemNotFound, address parse failures, slide-index errors, and compose-vs-read mismatches are enriched in the failure envelope with available_sheets, nearest_name_suggestions, parsed_address, slide_count, item_mode, and a recoveryHint — so the model can self-correct without a second round-trip.
• Self-healing CDP connection. If Excel closes unexpectedly, the server detects the dead connection on the next tool call, stops the stale sideload registration, relaunches Excel (including the dev server if needed), resets the session pool, and retries the original operation — no agent intervention required. Only activates when the server owns the launch (via --launch-addin or a prior addin.launch call); attaching to an external --browser-url endpoint is never disturbed.
• Progress notifications on long operations. addin.launch, addin.ensureRunning, and macro replay stream MCP $/progress notifications at each phase boundary (dev-server start, sideload, CDP-ready wait, step execution) so clients can show a live status bar instead of a silent spinner.
• Cross-host orchestration. office.embed reads a range from Excel and inserts it onto a PowerPoint slide in one call.
• Page automation fallback. page.* / pages.* / inspect.* / interact.* cover screenshot, snapshot, click, fill, type, hover, navigate, evaluate, wait, console log, network log — same primitives against headless Chrome on macOS/Linux.
• Per-host `runScript` escape hatch. excel.runScript, word.runScript, outlook.runScript, powerpoint.runScript, onenote.runScript run arbitrary <Host>.run callbacks when the workflow surface isn't enough.

Requirements

Install

npm (recommended)

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

Or run on demand without installing:

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

Pre-built binaries for Windows x64, macOS (Intel + Apple Silicon), and Linux (x64 + ARM64) ship via optional npm dependencies — the correct binary is fetched automatically.

Build from source

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

Use it in Claude Code

One command registers the server globally:

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

Or add it manually. Project scope (.claude/mcp.json in the repo) or user scope (~/.claude.json → mcpServers) both work:

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

Then, in any Claude Code session:

1. Open the Office host (see Office host setup below) so the WebView2 debug port is listening.
2. Ask Claude to do something — e.g. "Summarize the workbook, then pivot the Sales sheet by region." It will pick excel.summarizeWorkbook and excel.query automatically.
3. Run /mcp in Claude Code to inspect the tool list, or claude mcp list from a shell.

Tip: pass --launch-addin and Claude can sideload the add-in project under the current working directory automatically. No manual env var needed.

Use it in other MCP clients

<details> <summary><strong>VS Code (GitHub Copilot)</strong></summary>

Workspace config at .vscode/mcp.json:

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

Or: Command Palette → MCP: Add Server → paste the command. </details>

<details> <summary><strong>Cursor</strong></summary>

~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

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

</details>

<details> <summary><strong>Codex (OpenAI)</strong></summary>

~/.codex/config.toml:

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

</details>

<details> <summary><strong>Windsurf</strong></summary>

~/.codeium/windsurf/mcp_config.json:

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

</details>

<details> <summary><strong>Any MCP-compatible client</strong></summary>

• command: npx
• args: ["-y", "@dsbissett/office-addin-mcp@latest"]
• transport: stdio

</details>

Office host setup

Office hosts only expose their WebView2 runtime to CDP when started with a debug-port env var. The variable is shared across every Office app, so the same setup works for all five:

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

Command Prompt

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

The server probes http://127.0.0.1:9222 by default. Override with --browser-url or --ws-endpoint. Or skip the setup entirely with --launch-addin — the server will detect the Office add-in project under cwd and sideload it through office-addin-debugging.

Tool surface

Phase 0 of PLAN-workflow-surface.md deleted the raw cdp.* surface; everything below is the workflow-shaped replacement. Each workflow tool is one MCP call → one Office.js batch → one CDP round-trip.

Excel

Word

Outlook

PowerPoint

OneNote

Cross-host & macros

Add-in lifecycle & generic page automation

MCP Resources

LLM clients can reference Office state by URI instead of re-fetching it every turn. Five resource templates are registered on startup:

Resources support resources/subscribe. The server polls fingerprints every 30s and emits notifications/resources/updated when content changes; resources/unsubscribe (or client disconnect) tears down the polling goroutine.

Performance notes

• urlPattern selects the WebView2 page by substring match against the target URL. After the first call against a session, the selector cache drops diagnostics.cdpRoundTrips from ~3 to 1 on subsequent calls.
• The session pool allows 3 reconnects per 60-second window. Exhaustion surfaces as connection/session_acquire_failed. If the server owns the launch, it attempts one automatic stop+relaunch cycle before surfacing that error, so transient Excel restarts are transparent to the agent.
• DocCache snapshots are atomic-rename writes, mode 0600. Disable with --no-doccache.

Flags & environment variables

The binary takes no positional subcommands — it speaks MCP over stdio. The legacy call / daemon / serve --stdio subcommands have been removed.

Layout

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

License

MIT