groupdocs-search-mcp

GroupDocs.Search MCP サーバー

GroupDocs.Search を、Claude、Cursor、GitHub Copilot などの MCP エージェントから呼び出せるツールとして公開する MCP サーバーです。PDF、Office、メール、アーカイブなど、70 種類以上のドキュメント形式のフォルダーをローカルでインデックス化し、全文検索、ブール検索、フレーズ検索、あいまい検索、日付範囲検索に対応します。ドキュメントがマシンの外部に送信されることはありません。

インストール

ワンクリックインストールでは、サポートされているすべての設定があらかじめ入力されます。インストール後、ボリュームマウント内のホストパスのプレースホルダーを編集してください。GROUPDOCS_LICENSE_PATH が空の場合、評価モードで実行されます。

その他のクライアント — Claude Code、Codex CLI、Visual Studio 2022、Cursor、Windsurf、Cline、JetBrains Rider 用の設定例は、install/generated/ にあります。

この製品は Docker（GHCR）経由でのみ提供されます。 GroupDocs.Search エンジン DLL は約 200 MiB で、ONNX Runtime のネイティブライブラリも含むため、パッケージ化されたツール（約 281 MiB）は NuGet.org の 250 MB 制限を超えます。そのため、dnx と dotnet tool install は利用できません。より軽量なエンジンが制限内に収まるようになれば、標準の NuGet フローが復活します（.github/workflows/publish_prod.yml の差し戻しに関する注記を参照）。

docker run --rm -i \
  -v $(pwd)/documents:/data \
  ghcr.io/groupdocs-search/search-net-mcp:latest

イメージはマルチアーキテクチャ（linux/amd64 + linux/arm64）に対応し、latest タグに加えて、リリースごとに変更されないバージョンタグ（例：:26.10.1）が付与されます。バージョンを固定するには、:latest をバージョンタグに置き換えてください。共有設定や CI では、この方法をおすすめします。

Linux：コンテナーを自分のユーザーとして実行する

イメージは非 root ユーザー（uid 1654）で実行されます。Linux では、マウントしたフォルダーのホスト側の所有者が維持されるため、自分が所有するフォルダーはコンテナー内で読み取り専用となり、インデックス作成に失敗して "The index folder … is not writable" と表示されます。--user を追加すると、コンテナーは自分のユーザーとして書き込みます。

docker run --rm -i --user "$(id -u):$(id -g)" \
  -v $(pwd)/documents:/data \
  ghcr.io/groupdocs-search/search-net-mcp:latest

MCP クライアントの設定（JSON）ではシェルを実行できないため、数値を直接指定してください。id -u と id -g で数値を確認できます。通常は 1000 です。例："args": ["run", "--rm", "-i", "--user", "1000:1000", "-v", …]。Windows と macOS の Docker Desktop では、この指定は必要ありません。

インデックスの保存場所

GroupDocs MCP ファミリーの中で、検索は唯一のステートフルなサーバーです。インデックスとは、再起動後も保持される、ドキュメントのテキストの検索可能なコピーです。デフォルトでは、ドキュメントフォルダー内の .groupdocs-search-index フォルダー（コンテナー内の /data/.groupdocs-search-index）に保存されるため、上記のボリュームマウントだけで十分であり、インデックス自体がインデックス化されることもありません。

ドキュメントフォルダーが読み取り専用の場合は、専用のフォルダーにインデックスを保存してください。

docker run --rm -i \
  -v /path/to/documents:/data:ro \
  -v /path/to/index:/index -e GROUPDOCS_MCP_INDEX_PATH=/index \
  ghcr.io/groupdocs-search/search-net-mcp:latest

利用可能な MCP ツール

ツール	説明
add_to_index	ファイル、フォルダー（再帰的）、またはストレージフォルダー全体をインデックス化します。必要に応じてインデックスを作成します。
search	クエリに一致するドキュメントを関連度順に検索し、出現回数とともに JSON で返します。
get_text_fragments	一致した箇所とその前後の単語を返すため、エージェントはそれらを引用したり、内容に基づいて回答したりできます。
update_index	変更されたファイルを再読み込みし、インデックス化されたフォルダー内の新しいファイルを追加し、削除されたファイルを除外します。
remove_from_index	インデックス化されたパス（add_to_index に渡されたフォルダーまたはファイル）をインデックスから削除します。ディスク上のファイルは変更されません。
create_index	名前付きインデックス（contracts、hr/2026）を作成または開くか、空の状態で再作成します。
get_index_info	インデックスの有無、ドキュメント数、インデックス化されたパス、バージョン、その他のインデックスを JSON で報告します。
get_license_status	有効なライセンスモード（評価版／ライセンス済み／従量制）、エンジンのバージョン、および従量制の場合は消費量とクレジットを報告します。ドキュメントは処理しません。

パスは常にドキュメントフォルダーからの相対パス（contracts、reports/2026/q3.pdf）で指定します。インデックスはファイルシステムのパスではなく、名前で指定します。複数の名前付きインデックスを並行して保存できます。

クエリ構文（GroupDocs.Search DSL）：単語（invoice）、二重引用符で囲んだフレーズ（"force majeure"。引用符で囲んでいない複数語の入力は一致しません）、AND、OR、NOT と括弧、? 文字のワイルドカード（?ffect、princip?(2~4)）、daterange(2026-01-01 ~~ 2026-06-30)、数値の範囲（100 ~~ 500）、フィールドのプレフィックス（filename: lease）、^ で始まる正規表現、そして fuzzy 引数によるあいまい検索。

インデックス化できる形式には、PDF、DOC/DOCX、XLS/XLSX、PPT/PPTX、ODT/ODS/ODP、RTF、TXT、HTML、EPUB、FB2、EML/EMLX/MSG、PST/OST、ONE、ZIP が含まれます。アーカイブ内のドキュメントやメールの添付ファイルも対象です。エンジンが対応する全形式は、includeSupportedFormats: true を指定した get_index_info で確認できます。

AI エージェント向けのプロンプト例

サーバーに接続した後、以下のいずれかを Claude Desktop、Cursor、または GitHub Copilot Chat にコピーしてください。

1. フォルダーを検索可能にする：「contracts フォルダー内のすべてをインデックス化してください。」
2. 該当するドキュメントを探す：「どの契約書に解除違約金についての記載がありますか？」
3. ファイル一覧ではなく根拠を読む：「"force majeure" について書かれた段落を、それぞれの出典ファイルとともに表示してください。」
4. 最新の状態を保つ：「reports 内のファイルをいくつか編集しました。インデックスを更新して、Q3 予測をもう一度検索してください。」
5. コレクションを分ける：「HR フォルダー用に hr という名前のインデックスを作成し、育児休暇について検索してください。」

ライセンス

MCP サーバー自体は MIT ライセンスですが、基盤となる GroupDocs.Search エンジンを本番環境で使用するにはライセンスが必要です。 ライセンスがない場合、サーバーは評価モードで動作します。制限されるのは件数であり、ウォーターマークではありません。検索結果は完全に見えますが、実際にはそうではありません。

• 1 つのインデックスに保存できるドキュメントは最大 100 件です（リポジトリ内のすべてのインデックスを合計）。この件数に達すると、インデックス作成は停止します。
• 検索で返されるドキュメントは最大 10 件です。
• この制限が適用されている間は、すべてのツール応答に evaluation の注記が含まれます。
• 制限の全一覧：評価の制限。

サーバーのライセンス設定には 2 つの方法があります。

ライセンスファイル — GroupDocs.Search.lic（または GroupDocs.Total.lic）をコンテナーにマウントし、GROUPDOCS_LICENSE_PATH にそのパスを指定します。オフラインで動作します。

従量課金制 — GROUPDOCS_METERED_PUBLIC_KEY と GROUPDOCS_METERED_PRIVATE_KEY の両方を設定します。実際に処理した分だけ課金されます。AI エージェントの利用は突発的で事前に予測しにくいため、この方法が適しています。従量課金制のキーのペアとライセンスファイルの両方が設定されている場合は、従量課金制が優先され、ファイルは無視されます。

従量課金モードには外部への接続が必要です。 使用状況は GroupDocs サーバーに報告されるため、外部ネットワークから隔離された環境やファイアウォールで保護された環境では、その送信通信を許可する必要があります。または、代わりにライセンスファイルを使用してください。

いつでも get_license_status ツールを呼び出すと、現在のモードを確認できます。また、従量課金モードでは、消費量と残りのクレジットも確認できます。このツールはドキュメントを処理せず、何も変更しません。

秘密鍵を設定ファイルに記載しない方法

従量課金制の秘密鍵はシークレットです。MCP クライアントの設定はディスク上に通常のファイルとして保存され、プロジェクト単位の .mcp.json は慣例としてコミットされるため、次の方法を優先してください。

1. OS の環境変数に設定し、設定ファイルには一切記載しないでください。 stdio の MCP サーバーはクライアントの環境を引き継ぐため、この方法はどのクライアントでも使えます。macOS では、Finder から起動したアプリはシェルのエクスポートを引き継がない点に注意してください。launchctl setenv を使うか、ターミナルからクライアントを起動してください。
2. クライアントが対応している場合は、間接的に参照してください（Claude Code は ${VAR} を展開し、VS Code は ${env:VAR} と ${input:...} を使用します）。
3. ユーザー単位の設定ファイル（たとえば ~/.claude.json）への値の直接記載は、個人開発者であれば許容されます。
4. プロジェクト単位の .mcp.json にキーを直接記載してコミットすることは、絶対に避けてください。

Docker では、ファイルに書き込まずに値を引き渡してください。キーの値ではなく名前だけを指定することで、キーがコマンドラインに表示されないようにします。

docker run --rm -i \
  -e GROUPDOCS_METERED_PUBLIC_KEY -e GROUPDOCS_METERED_PRIVATE_KEY \
  -v /path/to/documents:/data \
  ghcr.io/groupdocs-search/search-net-mcp:latest

• 30 日間の無料一時ライセンスを取得
• ライセンスを購入 | 製品ページ

設定

変数	説明	デフォルト
GROUPDOCS_MCP_STORAGE_PATH	インデックス作成対象のドキュメントが格納されたフォルダー。ツールのパスはこのフォルダーを基準とします	./Files（イメージ内では /data）
GROUPDOCS_MCP_OUTPUT_PATH	(任意) 書き込み可能なフォルダー。GROUPDOCS_MCP_INDEX_PATH が設定されていない場合、インデックスはこのフォルダー内に保存されます	GROUPDOCS_MCP_STORAGE_PATH
GROUPDOCS_MCP_INDEX_PATH	(任意) インデックスを保存するフォルダー。インデックス名ごとにサブフォルダーが 1 つ作成されます	<output or storage>/.groupdocs-search-index
GROUPDOCS_LICENSE_PATH	コンテナー内から見た GroupDocs ライセンスファイルのパス。従量課金制のキーが設定されている場合は無視されます	（評価モード）
GROUPDOCS_METERED_PUBLIC_KEY	従量課金制の公開鍵。秘密鍵も必要です。GROUPDOCS_LICENSE_PATH より優先されます	（未設定）
GROUPDOCS_METERED_PRIVATE_KEY	従量課金制の秘密鍵。シークレットのため、コミット済みの設定ではなく環境変数から渡してください	（未設定）

GroupDocs.Search 22.7～26.8 で書き込まれたインデックスは、初めて開く際に 26.10 形式に変換されます。元のインデックスは <name>.pre-26.10-backup として隣に保持されます。

Claude Desktop での使用方法

{
  "mcpServers": {
    "groupdocs-search": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "/path/to/documents:/data", "ghcr.io/groupdocs-search/search-net-mcp:latest"]
    }
  }
}

ライセンスを使用するには、イメージ名の前に "-v", "/path/to/license-folder:/license", "-e", "GROUPDOCS_LICENSE_PATH=/license/GroupDocs.Total.lic" を追加してください。 バージョンを固定するには、:latest をリリースタグに置き換えてください。

VS Code / GitHub Copilot での使用方法

上記の VS Code にインストール ボタンを使用するか、.vscode/mcp.json （install/generated/vscode-mcp.json にもあります）に追加してください。

{
  "inputs": [
    {
      "type": "promptString",
      "id": "storage_path",
      "description": "Folder with the documents to index.",
      "password": false
    }
  ],
  "servers": {
    "groupdocs-search": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "${input:storage_path}:/data", "ghcr.io/groupdocs-search/search-net-mcp:latest"]
    }
  }
}

Docker Compose での使用方法

cd docker
docker compose up

docker/docker-compose.yml を編集し、ボリュームがローカルのドキュメントフォルダーを指すようにしてください。

ドキュメントとガイド

ステップごとのデプロイガイドと、公開済みイメージの統合テストスイートは、関連リポジトリ GroupDocs.Search.Mcp.Tests にあります。

• Docker 経由で実行する
• MCP レジストリで確認する
• Claude Desktop で使用する
• VS Code / GitHub Copilot で使用する
• 統合テストを実行する

ライセンス

MIT — LICENSE を参照してください。