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

Requirement	Notes
Office on Windows 10/11	Required for all *.runScript / *.query / *.discover / *.applyDiff / addin.* tools — Office only uses WebView2 on Windows
Node.js 14+	For the npx install path
Go 1.22+	Only needed to build from source
macOS / Linux	Supported for page.* / pages.* against headless Chrome (no Office)

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

Tool	Purpose
excel.summarizeWorkbook	Sheets, tables, named ranges, used-range bounds — single call
excel.tabulateRegion	Load a range, return rows-as-objects + per-column type tags
excel.query	Server-side filter / project / groupBy / agg / limit DSL
excel.discover	Persistent workbook fingerprint snapshot (doccache)
excel.applyDiff	Batch cell/range patches in one Excel.run
excel.runScript	Run an arbitrary Excel.run callback

Word

Tool	Purpose
word.discover	Document structure snapshot
word.applyEdits	Batch find/replace edits in one Word.run
word.runScript	Run an arbitrary Word.run callback

Outlook

Tool	Purpose
outlook.query	Query the mailbox / current item
outlook.discover	Mailbox + active-item snapshot
outlook.draftReply	Set subject and/or body on a compose-mode item
outlook.runScript	Run an arbitrary callback against Office.context.mailbox

PowerPoint

Tool	Purpose
powerpoint.query	Slide-level query DSL
powerpoint.discover	Deck structure snapshot
powerpoint.rebuildSlideFromOutline	Rewrite a slide's title and/or body bullets
powerpoint.runScript	Run an arbitrary PowerPoint.run callback

OneNote

Tool	Purpose
onenote.query	Notebook / section / page query DSL
onenote.discover	Notebook structure snapshot
onenote.appendToPage	Append HTML and/or bullets to a page
onenote.runScript	Run an arbitrary OneNote.run callback

Cross-host & macros

Tool	Purpose
office.embed	Read an Excel range and insert it on a PowerPoint slide
macro.record_start	Begin capturing subsequent tool calls into a named macro
macro.record_stop	Finalize and persist the macro to disk
macro.<name>	Replay a persisted macro (auto-registered on next startup)

Add-in lifecycle & generic page automation

Tool group	Purpose
addin.*	ensureRunning (start here — probes then launches if needed), launch, stop, detect, status, contextInfo, cfRuntimeInfo, openDialog, dialogSubscribe, dialogClose, listTargets
page.*	screenshot, snapshot, click, fill, typeText, hover, navigate, evaluate, pressKey, waitFor, consoleLog, networkLog, networkBody
pages.*	list, select, close, handleDialog
inspect.* / interact.*	DOM / accessibility inspection and higher-level interaction primitives

MCP Resources

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

URI template	Backed by
office://excel/<workbook>/<sheet>!<range>	excel.tabulateRegion
office://word/<doc>/bookmark/<name>	word.runScript (inline script)
office://outlook/<folder>	outlook.query
office://pp/<deck>/slide<N>	powerpoint.query
office://onenote/<notebook>/<section>/<page>	onenote.query

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

Flag	Env	Default	Description
--browser-url	—	http://127.0.0.1:9222	WebView2 / Chrome debug endpoint
--ws-endpoint	—	—	Direct browser WebSocket URL (overrides --browser-url)
--log-file	—	stderr	Append diagnostics to a file instead of stderr
--log-level	—	info	slog level: debug, info, warn, error
--launch-addin	—	off	Auto-detect and sideload the Office add-in project under cwd at startup, only if no CDP endpoint is reachable
--launch-excel	—	off	Deprecated alias for --launch-addin
--no-doccache	—	off	Disable the persistent document discovery cache (*.discover still runs; reads/writes to doccache.json are skipped)
--allow-dangerous-cdp	OAMCP_ALLOW_DANGEROUS_CDP	off	Enable crash/terminate CDP methods
--version	—	—	Print binary version and exit

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