docx4j Word documents

docx4j-mcp

Model Context Protocol サーバーです。AI エージェントが docx4j のエンジンを利用して、Claude Desktop、Claude Code、または任意の MCP クライアントから Word（.docx）文書の読み取り、変換、入力を行えます。

エンジン：docx4j 17.1.0（サーバーのバージョンは独立しています。同梱されている docx4j のバージョンは pom、サーバーの起動ログ、および MCP の指示に記載されています）。

MCP プロトコル：2025-11-25（Java SDK 2.0.1、現在利用可能な最新バージョン）。2026-07-28 仕様に対応するクライアントは、2 つの時代にまたがるフォールバックを実装していれば動作します。server/discover のプローブで JSON-RPC -32601 が返され、クライアントが initialize にフォールバックします（stdio 経由で検証済み）。フォールバックを備えていない最新仕様専用のクライアントは、SDK による 2026-07-28 対応（マイルストーン 2.2）がリリースされるまで接続できません。その時点で、このサーバーも移行する予定です。

ステータス：フェーズ 3 — リリース済みの docx4j 17.0.4 に対し、すべてのツールが stdio 経由で動作します。実行可能 jar、.mcpb バンドル、OCI イメージ、Claude Code プラグインとしてパッケージ化されています。計画、ツールの提供範囲、フェーズ分けについては CR-mcp-server.md をご覧ください。

ビルド

JDK 17 以降が必要です。docx4j のすべての依存関係（docx4j 17.1.0、ImportXHTML 17.0.4）は Maven Central から取得します。

mvn package            # -> target/docx4j-mcp.jar (shaded, runnable)
mvn test               # JUnit 5 tests against the tool handlers directly

実行

java -jar target/docx4j-mcp.jar --root /path/to/documents [--root ...] [--max-inline-chars N]

ルートとして、ディレクトリを引数に直接指定することもできます（.mcpb バンドルのフォルダーピッカーから渡される形式です）。

Claude Desktop、ワンクリック

GitHub リリースから docx4j-mcp.mcpb をインストールし（Settings → Extensions）、サーバーがアクセスできるフォルダーを選択すれば完了です。packaging/build-mcpb.sh でローカルにビルドできます。PATH に Java 17 以降が必要です。

Docker

docker run -i --rm -v /path/to/documents:/data ghcr.io/plutext/docx4j-mcp

（ツール呼び出し内のパスは、/data 以下のコンテナ内パスになります。 ローカルでビルドするには packaging/docker/Dockerfile を使用します）。

Claude Code プラグイン

packaging/claude-plugin/ には、サーバー設定とテンプレート／文書作成ワークフロー用のスキルが含まれています。DOCX4J_MCP_JAR（jar へのパス）を設定し、必要に応じて DOCX4J_MCP_ROOTS も設定してください。

リリース

vX.Y.Z のタグを付けると、.github/workflows/release.yml が jar と mcpb をビルドして GitHub リリースに添付し、ghcr.io/plutext/docx4j-mcp にプッシュするとともに、GitHub OIDC 経由で server.json（sha を記入済み）を公式 MCP レジストリに公開します。

エージェントが渡す各ファイルパスは、--root ディレクトリのいずれかの内部に解決される必要があります（シンボリックリンクは先に解決されます）。デフォルトのルートはありません。ルートを指定せずにサーバーを起動すると、起動は拒否されます。ログは stderr に出力され、stdout はプロトコル用です。テキストをインラインで返すツールは、--max-inline-chars（デフォルトは 200000）で上限を設定します。上限を超えた場合は output_path に書き込むか、マーカーを付けて切り詰めます。

Claude Code（プロジェクト内の .mcp.json）

{
  "mcpServers": {
    "docx4j": {
      "command": "java",
      "args": ["-jar", "/path/to/docx4j-mcp.jar", "--root", "/path/to/documents"]
    }
  }
}

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "docx4j": {
      "command": "java",
      "args": ["-jar", "/path/to/docx4j-mcp.jar", "--root", "/Users/you/Documents"]
    }
  }
}

ツール

ツール	機能
describe_template	テンプレートが求めるデータを確認します。スケルトン XML と xpaths／条件（OpenDoPE、バインドされたコンテンツコントロール）、または MERGEFIELD 名と書式スイッチ（差し込み印刷）を取得します。fill_template の前に呼び出してください。
fill_template	書式を維持したままテンプレートに入力します。data は XML 文字列（OpenDoPE／バインドされたコントロール。繰り返しと条件を処理）または JSON オブジェクト（差し込み印刷）です。
convert_to_pdf	XSL-FO／Apache FOP を使用して docx → PDF に変換します。数式と WMF／EMF 図形はベクターとしてレンダリングされます。update_toc は任意で指定でき、フォントの置換を報告します。メトリック互換フォント（Carlito、Caladea、Liberation、Tinos など）がバンドルされています。
markdown_to_docx	Markdown → 適切にスタイル設定された docx に変換します（見出し、番号付け、GFM テーブル、脚注、タスクリスト、TeX 数式）。styles_template_path は任意で指定できます。
docx_to_markdown	docx → Markdown に変換します（構造を維持）。オプション：tracked_changes の承認／マークアップ、image_dir_path。
html_to_docx	docx4j-ImportXHTML を使用して HTML → docx に変換します。緩やかな形式の HTML も受け付けます（jsoup で正規化）。h1～h6 は見出しスタイルに対応します。styles_template_path は任意で指定できます。mode: altchunk を指定すると HTML が埋め込まれ、Word で開いたときに変換されます。リモート画像やスタイルシートは取得されません。
convert_to_html	docx → 単独で動作する HTML に変換します（ビジターエクスポーター。画像には image_dir_path を指定し、update_toc は任意で指定できます）。
extract_text	プレーンテキストを抽出します。段落／テーブルごとに 1 行です。

数式はエンドツーエンドでサポートされています。Markdown の TeX 数式 （$..$）と HTML の MathML は、実際に編集可能な Word 数式（OMML）になり、 数式は PDF（jeuclid／FOP 経由。LaTeX ツールチェーン不要）および HTML（ネイティブ MathML。JavaScript 不要）出力でもレンダリングされます。既知の制限事項：非常に長い単一の ディスプレイ数式は、PDF では 1 つの分割できない画像となり、行折り返しされません。

書き込みツールは output_path を受け取り、overwrite: true が指定されていない限り上書きを拒否します。

例（Claude Code）

contracts/nda-template.docx に対して describe_template を使い、Acme Pty Ltd 向けに入力して contracts/nda-acme.docx に書き込み、その後 PDF に変換してください。

エージェントはスケルトン XML（または MERGEFIELD 名）を取得して入力し、fill_template と convert_to_pdf を呼び出します。結果から、書き込まれた内容と置換されたフォントがわかります。

ライセンス

Apache License 2.0。