office-addin-mcp

office-addin-mcp

あらゆる MCP クライアントから Excel、Word、Outlook、PowerPoint、OneNote のアドインを操作できます。Model Context Protocol を stdio 経由で話す Go バイナリが 1 つあれば実現できます。

office-addin-mcp は、Office.js アドインをホストするために Office が使用する WebView2 ランタイムに接続し、LLM クライアントに高レベルのツール群を提供します。モデルに 15 個の生の Office.js プリミティブを連携させる方法を学習させる代わりに、サーバーはワークフローごとに 1 つのツール呼び出しを提供します。

最新リリース · CHANGELOG.md · PLAN-workflow-surface.md をご覧ください。

主な特長

• プリミティブではなく、ワークフローツール。 excel.tabulateRegion、word.applyEdits、outlook.draftReply、powerpoint.rebuildSlideFromOutline、onenote.appendToPage、excel.summarizeWorkbook は、それぞれ以前は 5～20 回必要だった呼び出しを、1 つの Office.js バッチ（CDP の往復 1 回）にまとめます。
• サーバー側のクエリ 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 が追加されるため、2 回目の往復なしでモデルが自力で修正できます。
• 自己修復型の CDP 接続。 Excel が予期せず終了した場合、サーバーは次のツール呼び出し時に接続切断を検知し、古いサイドロード登録を停止して Excel を再起動し（必要に応じて開発サーバーも起動）、セッションプールをリセットして元の操作を再試行します。エージェントの介入は不要です。サーバー自身が起動した場合（--launch-addin または以前の addin.launch 呼び出し経由）のみ有効です。外部の --browser-url エンドポイントへの接続には影響しません。
• 長時間処理の進捗通知。 addin.launch、addin.ensureRunning、マクロの再生では、各フェーズの境界（開発サーバーの起動、サイドロード、CDP 準備完了待ち、ステップの実行）で MCP $/progress 通知がストリーミングされるため、クライアントは回転表示だけでなく、ライブのステータスバーを表示できます。
• ホスト間のオーケストレーション。 office.embed は Excel から範囲を読み取り、1 回の呼び出しで 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 で使う

1 つのコマンドでサーバーをグローバルに登録できます。

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 シートを地域別にピボットしてください。」 と依頼します。Claude は excel.summarizeWorkbook と excel.query を自動的に選択します。
3. Claude Code で /mcp を実行してツールの一覧を確認するか、シェルから 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 アプリで共有されるため、次の同じ設定を 5 つすべてで使用できます。

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.* インターフェースを削除しました。以下のすべてが、ワークフローに合わせた代替機能です。各ワークフローツールは、1 回の MCP 呼び出し → 1 回の Office.js バッチ → 1 回の CDP ラウンドトリップで構成されます。

Excel

Word

Outlook

PowerPoint

OneNote

ホスト間連携とマクロ

アドインのライフサイクルと汎用ページ自動化

MCP リソース

LLM クライアントは毎回再取得する代わりに、URI を使って Office の状態を参照できます。起動時に5つのリソーステンプレートが登録されます。

リソースは resources/subscribe をサポートしています。サーバーは30秒ごとにフィンガープリントをポーリングし、内容が変更されると notifications/resources/updated を送信します。resources/unsubscribe（またはクライアントの切断）により、ポーリング用ゴルーチンが終了します。

パフォーマンスに関する注意事項

• urlPattern は、対象 URL との部分一致によって WebView2 ページを選択します。セッションに対する最初の呼び出し後は、セレクターキャッシュにより、以降の呼び出しで diagnostics.cdpRoundTrips が約3から1に減少します。
• セッションプールでは、60秒間に3回まで再接続できます。上限に達すると connection/session_acquire_failed が発生します。サーバーが起動を管理している場合、このエラーを通知する前に停止と再起動を1回自動で試みるため、一時的な Excel の再起動はエージェントからは透過的です。
• 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