WordMcp — Microsoft Word MCP サーバー

MCP サーバーで、AI アシスタントが COM オートメーション経由で Windows 用 Microsoft Word を操作できるようにします。ドキュメントを開く、テキストを読み取って編集する、段落と表を管理する、ドキュメントのプロパティを設定する、PDF にエクスポートするなどの操作ができます。

Windows のみ。 ローカルに Microsoft Word がインストールされている必要があります — このサーバーは実際の Wordアプリを自動化するもので、.docx ファイルを直接解析するものではありません。

要件

Related MCP server: Word Document MCP Server

インストール

dotnet tool install --global WordMcp.McpServer

この後、ツールは mcp-word として利用できます。

mcp-word --version
mcp-word --help

後で更新または削除する場合:

dotnet tool update --global WordMcp.McpServer
dotnet tool uninstall --global WordMcp.McpServer

未リリースのビルドを実行するには、代わりにローカルでパックし、出力フォルダーからインストールします:

dotnet pack src\WordMcp.McpServer\WordMcp.McpServer.csproj -c Release -o artifacts
dotnet tool install --global --add-source .\artifacts WordMcp.McpServer

インストールしない場合

このサーバーは MCP レジストリ に io.github.trsdn/mcp-server-word として登録されています。トールパッケージを自分で解決できるクライアントは、グローバルツールを置く代わりに、要求に応じて内容を取得する dnx から実行できます:

{
  "servers": {
    "word": {
      "type": "stdio",
      "command": "dnx",
      "args": ["WordMcp.McpServer@0.1.0", "--yes"]
    }
  }
}

クライアント設定

サーバーは stdio で通信します。

VS Code / GitHub Copilot

.vscode/mcp.json:

{
  "servers": {
    "word": {
      "type": "stdio",
      "command": "mcp-word"
    }
  }
}

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "word": {
      "command": "mcp-word"
    }
  }
}

Copilot CLI

copilot mcp add word --command mcp-word

概念

すべての操作は セッション 内で行われます。セッションは 1 つの Word インスタンスと 1 つの開いているドキュメントを保持し、word-a1b2c3d0 のような session_id で識別されます。

file(open|create) ──► session_id ──► text / paragraph / table / document ──► file(save) ──► file(close)

• パスは 絶対パス で指定します (C:\Users\me\Documents\report.docx)。

• 対応している入力形式: .docx、.docm、.doc、.dotx、.dotm、.rtf。

• ドキュメントは Word で既に開いていた状態では利用できません — WordMcp はファイルへの排他アクセスが必要です。

• Word はバックグラウンドで目に見えない状態で実行され、セッションを閉じる時に終了します。

セッション サービス

セッションは通常、MCP サーバー のプロセス内に閉じ、プロセスと一緒に消えます。WordMcp.Service.exe は任意のバックグラウンド デーモンであり、代わりにセッションを保持します。これにより、セッションは再起動したクライアントを越えて残り、複数クライアントで共有できます。

WordMcp.Service.exe --daemon [--idle-minutes 30]   # listen until idle or stopped
WordMcp.Service.exe --status                       # what is it doing?
WordMcp.Service.exe --stop                         # save open documents and exit

手動で実行する必要はほぼありません — このデーモンを使うクライアントは、必要になった時に自動起動します。デーモンが待ち受けるパイプには、そのユーザーの SID が埋め込まれ、その SID に ACL が設定されているため、セッションが他のアカウントと共有されることはありません。アイドルタイムアウトの間、セッションが開かれなければ、自動的に終了します。

利用するには、MCP サーバーに WORDMCP_SERVICE_MODE=daemon を設定します。するとすべてのツール呼び出しは、サーバー自身のプロセス内ではなくデーモンへと渡って実行されます。指定しない場合は、サーバーがセッションをすべて自分自身で保持します。これは単一クライアントにとって適切な構成です: 別プロセスも起動待ちも発生しません。

ツール

ツールは 15 個あり、それぞれ action パラメーターを受け取ります。

file — セッション ライフサイクル

file(action: "open", path: "C:\\Users\\me\\Documents\\report.docx")
// → { "sessionId": "word-a1b2c3d4e5f6g", "fileName": "report.docx", ... }

text — コンテンツ

文字位置は get と find から取得でき、これらは Word の指定範囲オフセットです。

paragraph — 構造

段落のインデックスは 1 から始まります。Word と同じ考え方です。

table — 表

document — メタデータとエクスポート

image — 画像

field — フィールドと目次

section — セクションとページ設定

header-footer — ヘッダーとフッター

kind は header まはた footer を指定し、type は primary、first-page、even-pages のいずれかを指定します。

style — スタイル

style_type は paragraph、character、table、list のいずれかを選択します。全表示には in_use_only: false を渡します。ローカライズされた Word では 370 件を超えるスタイルがあります。

style(action: "create", session_id: "...", name: "Callout", base_style: "Normal")
style(action: "modify", session_id: "...", name: "Callout",
      font_size: 11, bold: true, color: "#C00000", space_after: 12)

list — 箇条書きとリスト番号

end_index を省略すると、start_index にのみ操作が適用されます。

list(action: "apply", session_id: "...", start_index: 2, end_index: 5, list_type: "number")
list(action: "set-level", session_id: "...", start_index: 3, end_index: 4, level: 2)
list(action: "restart", session_id: "...", start_index: 6)

comment — レビューコメント

add は、anchor_text で段落中の語句を指定しない限り、段落全体にコメントを結び付けます。delete を行うとインデックス配列がずれるため、2 件目のコメントを削除する前に再度 list を実行してください。

comment(action: "add", session_id: "...", paragraph_index: 4,
        text: "Source?", anchor_text: "fifteen percent")
comment(action: "list", session_id: "...", unresolved_only: true)

revision — 殺し込み変更

accept / reject で index を省略すると、ヘッダー/フッターを含む文書全体が処理されます。

revision(action: "set-tracking", session_id: "...", enabled: true)
revision(action: "accept", session_id: "...")

bookmark — 安定した参照

名前は文字で始まる必要があり、文字・数字・アンダースコアのみを含めることができます。ブックマークはドキュメント内の他の場所での編集後も存続するため、段落インデックスがずれた後で一節を読み返すための信頼できる方法になります。

bookmark(action: "add", session_id: "...", name: "Intro", paragraph_index: 2)
bookmark(action: "add", session_id: "...", name: "Growth",
         paragraph_index: 4, anchor_text: "fifteen percent")
bookmark(action: "get-text", session_id: "...", name: "Intro")

screenshot — ページを表示する

レイアウトの疑問 — ページ区切り、テーブル幅、画像配置、ヘッダー位置 — は、測定値からよりも描画されたページから得た方がはるかに簡単です。PNGはファイルに書き込まれ、そのパスが返されます。include_image: true を追加すると、インラインのbase64としても返され、これは画像が実際に見られる場合にだけコンテキストに見合う価値があります。

dpi の既定値は150です。手軽なレイアウト確認には96、印刷に近い出力には300を使用します。

screenshot(action: "page", session_id: "...", page: 2)
screenshot(action: "page", session_id: "...", page: 1,
           output_path: "C:/temp/page1.png", dpi: 300, include_image: true)

レスポンス

すべてのツールはJSONを返します。失敗は、トランスポートエラーではなく構造化されたペイロードとして報告されます:

{
  "success": false,
  "isError": true,
  "tool": "text",
  "action": "Replace",
  "errorType": "KeyNotFoundException",
  "errorMessage": "Session 'word-unknown' not found."
}

既知の動作と落とし穴

• document(save-as) は元のファイルも保存します。 Wordには、フォーマットを変更する「コピーを保存」APIがありません。PDF以外のターゲットでは、サーバーは SaveAs2(target) を呼び出してから SaveAs2(original) を呼び出します。そのため、未保存の変更(original)が元ファイルに副作用として保存されます。副作用のないエクスポートが必要な場合は export-pdf を使用してください。

• 色は16進RGB (#0078D4)。サーバーはWordが期待するBGR値に変換します。

• 使用権保護されたドキュメント(IRM/AIP)は、Wordが起動される前に拒否されます。

• Wordで開いているドキュメントはセッションをブロックします。 先に閉じてください。

• Wordのダイアログは自動化を停止させます。 呼び出しがタイムアウトしたら、デスクトップにダイアログが開いていないか確認してください。

• スタイル名は英語です。 組み込みスタイル (Heading 1, Title, Table Grid, …) はWordの言語に依存しないスタイルIDに変換されるため、ローカライズインストールでも機能します。その他の名前はWordにそのまま渡されます。これがカスタムスタイルやローカライズスタイルの扱いです。Wordはスタイルをそのローカライズ名で「報告」することに注意してください(ドイツ語版では Überschrift 1)。これが style(list) が name と english_name の両方を返し、english_name がある場合はそれを送り返す必要がある理由です。

• 組み込みスタイルは削除できません。 style(delete) はWordの一般的なCOMエラーをそのまま返すのではなく、明確なメッセージで拒否します。段落に引き続き適用されているカスタムスタイルも削除できません。先にその段落などを別のスタイルに設定してください。

• 新しいドキュメントは直接書き込まれ、経由ではなく書き込まれます。 file(create) は空 .docx/.docm パッケージ自体を書き込み、それを開きます。Wordを経由してドキュメントを作成すると、Microsoft 365 にサインインしている環境では信頼性がありません。Autosaveが新しいドキュメントをOneDriveへ囲い込み、要求されたローカルパスを告げに無視してしまうからです。

• マージされたテーブルセルは table(read) によって空文字列として返されます。

• 画像のサイズはピクセルではなくポイント(72 pt = 1 インチ)です。image(insert) と image(resize) は、lock_aspect_ratio が false に設定されていない限り縦横比を維持するため、width だけを渡しても高さは連動して拡大されます。

• image はインライン画像のみを対象にします。 フローティング図形、テキストボックス、グラフは変更されず、image(list) には表示されません。したがって、それらが存在しても画像インデックスはずれません。

• 目次は見出し段落のみを一覧にします。 見出しスタイルのないドキュメントでは field(insert-toc) は entry_count: 0 を返します。paragraph(add|set-style) で Heading 1/Heading 2 を適用してから、field(update-toc) を実行してください。

• field(update-all) はヘッダーとフッターも走査します。 Word の Document.Fields は本文のみをカバーするため、そのままだとページ番号が更新されません。

• image(insert) にキャプションを付けるとWordのキャプション番号が使われます。 そのため、キャプションは Figure 1 <your text> のようになります(非英語版ではローカライズ)し、図表目録の対象にも含まれます。

• すべての測定値はポイント単位です。ページ余白も含みます(1 cm = 28.35 pt、1 インチ = 72 pt)。

• section(page-setup) は余白よりも先に paper_size を適用します。 Wordでは紙サイズをを変更すると余白がリセットされるためです。 section_index を指定しない場合、設定はすべてのセクションに適用されます。

• ヘッダーとフッターはセクション間で継承されます。 新しいセクションには、何かが書き込まれるまで前のセクションのヘッダーが表示されます。section_index を付けた header-footer(set) はその関連付けを自動的に壊すため、セクション1は独自のテキストを保持しません。

• first-page および even-pages ヘッダーにはセクションの切り替えが必要です。 header-footer(set) が DifferentFirstPage や DifferentOddEvenPages をオンにします。これがないと、Word はテキストを保存しますが描画しません。

• list(apply) は既定で新しいリストを開始します。 continue_previous_list はオフです。関係ない以前のリストの番号を引き継ぐことは、意図しない場合がほとんどだからです。2つの番号付きリストが普通の段落だけでの中場合、独立性が保たれます。Wordがどうしても結合してしまう場合は list(restart) を使用してください。

• アウトライン番号付きリストだけが、レベルごとに異なる表示をします。 list(set-level) はどのリストにも動作しますが、通常の bullet または number リストではどのレベルでも同じマーカーが表示されます。段落が単にインデントされるだけです。

• comment(resolve) はMicrosoft 365で頻繁に失敗します。 Word のモダンコメントは、API を渡って追加されたすべてのコメントを未投稿の下書き見なし、下書きには「完了」をマークできません。サーバーは、明確なメッセージとして報告されます。代わりに削除してください。comment(list) は、状態を公開しないインストールでは resolved: null を戻します。

• コメントとリビジョンのインデックスは変わります。 コメントを削除するか、1つのリビジョンを受け入れると、後継のすべての番号が振り直されます。そのため、古いインデックスを再利用するのではなく、2つのそのような呼び出しの間に list を再実行してください。

• インデックスを指定しない revision(accept|reject) もヘッダーとフッターを走査します。 Wordの Document.AcceptAllRevisions() は本文だけ処理するので、field(update-all) と同じ欠落をきたします。

• トラックされる変更は、追跡が入っている間だけ記録されます。 revision(set-tracking) は遡って適用されません。変更を記録したい操作の前にオンにしてください。

• ブックマーク名はWordによって制限されています。 名前は文字で始まる必要があり、文字・数字・アンダースコアのみを使用でき、40文字以内に制限されています。スペース、ハイフン、ピリオド、ASCII以外の文字は、コールがWordに届く前に拒否されます。Wordに渡すと、ウィンドウのCOMエラーになるためです。

• ブックマークは、文章を参照する安定した方法です。 段落インデックスは挿入のたびにずれるため、ブックマークは維持されます。1回ブックマークしておくと、後から bookmark(get-text) で再利用できます。

• 段落に対する bookmark(add) は段落記号を除外します。 そのため get-text は末尾の改行のないテキストを返します。複数の段落のブックマークは、途中の段落記号を保守します。

• screenshot(page) はPDFを介してレンダリングします。 Word にはページを画像として返すAPIがないため、サーバーは ExportAsFixedFormat でページを書き出し、ラスタライズします。未保存の変更も含まれ，一時的なPDFは後に削除されます。

• ページ番号は新しいページ割り付けから取得されます。 自動化のみで編集されたページ数は、古いページ数が報告されます。screenshot はまずページ数を再計算します。つまり、ページのページ数は、開いた時点ではなく、現在のレイアウトを反映します。

ソースからビルドする

git clone https://github.com/trsdn/mcp-server-word.git
cd mcp-server-word
dotnet build WordMcp.sln -c Release
dotnet test WordMcp.sln --filter "Category!=RequiresWord"

プロジェクトレイアウト

生成されたツールレイヤー

15個のツールのうチ14個はビルド時渡生成されます。src/WordMcp.Core/Commands 内のコマンドインターフェースが、ワイヤー契約の唯ーの情報源です:

• [ServiceCategory("section", "Section")] はツールクラスの名前を指定します。WordSectionTool。

• [McpTool("section", Title = ..., Description = ...)] は、ツール名とモデルが読むプロンプトを提供します。

• 各メソッドの [ServiceAction("page-setup")] は、生成された WordSectionAction 列挙型の値になります。

• インターフェースのパラメータの XML ドキュメントが、MCP スキーマのパラメータ説明になります。

ジェネレーターはすべてのアクションのパラメータを1つのメソッドに統合するため、一部のアクションだけが使用するパラメータは省略可能として出力されます。APIを変更するには、インターフェースを編集してください。生成されたコードは編集しないでください。file はセッションを管理するため、単一のセッションを操作するのではなく、手書きのまま読まれています。

src/WordMcp.McpServer/obj/generated 以下で生成されたコードを確認してください。GeneratedToolContractTests のテストは生成されたAPIをインターフェースと比較するため、不一致はクライアントに届く前にビルドが失敗します。

実際のWordインストールや必要とするテストは [Trait("Category", "RequiresWord")] でマーされ、CIでは除外されています。失敗した統合テストの実行によって、孤立した WINWORD.EXE プロセスが残ることがあります。それらは後の実行を遅くしたりブロックしたりするため、再実行後の前に Get-Process WINWORD | Stop-Process -Force でクリーンアップしてください。

その他の参照

トラブルシューティング

コントリビューティング

バグ報告と機能リクエストは[issueテンプレート](https://github.com/trsdn/mcp-server-word/issues/new/choose)からお願いします。
プルリクエストも歓迎です。[CONTRIBUTING.md](CONTRIBUTING.md)には、ビルド方法、テストスイートの2つの部分の実行方法、
そしてツールを追加するために必要なことが記載されています。

先に[行動規範](CODE_OF_CONDUCT.md)をお読みください。

**セキュリティの問題は公開のIssueで報告しないでください** — [セキュリティポリシー](SECURITY.md)に記載されているように、非公開で報告してください。

## ライセンス

MIT — [LICENSE](LICENSE)を参照してください。