Matrix

Claude Code 向け Matrix

Claude Code はコードを grep できますが、PDF、Word ファイル、スキャン画像、グラフを意味で検索することはできません。Matrix は、文書フォルダーを対象に、ファイル、ページ、該当箇所の引用や、複数の文書にまたがる規定間の相互参照や表を含むローカルのセマンティックインデックスを提供します。すべてコンピューター上で実行され、言語モデルには Claude Code 自体を使うため、追加のモデルや API キーは不要です。DEMO.md では、公開文書 442 ページと 1,592 ページを対象に、Claude Code 単体の場合と比較しています。

なぜ使うのか

Claude Code 単体の場合とプラグインを使った場合を、2 回測定しました（数値、質問、正解は DEMO.md にあります）。EU 規則と報告書の 442 ページ（質問 4 件、各 2 回実行）と、4 言語の 14 文書、1,592 ページ（バージョン 0.2.3、質問 4 件、各 1 回実行）が対象です。

• 大量の文書を扱う際の労力を軽減できます。 442 ページの場合、質問あたり平均 126 秒から 42 秒に短縮され（約 3 倍。質問によって 2～4 倍）、ツール呼び出しは半分以下（21.4 回から 9.5 回）、入力トークンも半分以下（651 k から 303 k）になりました。1,592 ページの場合、所要時間は 35％短縮され（4 件の質問で 180 秒から 117 秒）、入力トークンは 34％減少（615 k から 405 k）、出力トークンは 60％減少し、ラウンド数は半分になりました。効果が最も大きいのは、ある規定について別の言い回しや別の言語で尋ねる場合です。複数の法令にまたがる答えを探す場合は、効果が最も小さくなります（ほとんど効果はありません。いずれの場合も Claude は法令ごとに 1 回検索するためです）。
• 一度インデックスを作成すれば、何度でも質問できます。 インデックス作成はコンピューター上で一度実行され、Claude のトークンを消費しません。インデックスはセッションをまたいで保持され、自動的にフォルダーを追跡します。同じ文書について追加で質問するたびに、処理が速くなり、使用するトークンも少なくなります（DEMO.md）。文書が多い、または長い場合、同じ文書セットについて追加の質問をする可能性が高い場合、答えに根拠を求める場合に効果があります。たとえば、契約書、規則、プロジェクトファイル、技術マニュアル、研究、議事録、報告書などです。一度限りの質問であれば、Claude が自分でファイルを検索することもできます。また、回答にファイル内の根拠がない場合は、その旨を伝えます。
• ファイル、条文、該当箇所を示し、本文と照合した引用を提示します。 両方のテストですべての回答に、正しい文書、条文、該当箇所が示されました。大規模な文書セットでは、ページをまたぐ該当箇所でページ番号が 2 件ずれていました（既知の問題で、未修正です）。Claude Code 単体ではページ番号も正確でした。
• 言い換え、スキャン画像、グラフを見つけます。 意味に基づいて検索するため、本文とは異なる言い回しの質問でも該当する規定を見つけられます。また、グラフにしかない値も、グラフのあるページから見つけられます。30 件のテスト質問では、正しい箇所が検索結果の最初に表示されたのは 17 件（0.2.2 では 12 件）、上位 5 件以内に表示されたのは 27 件（以前は 19 件）でした。オプションの再ランキングモデルを使った場合です。検索結果 1 件あたりのトークン数は約 5,500 から約 1,160 になります。複数の言語が混在するフォルダーでは、文書と同じ言語で検索すると最も効果的です。スキルは Claude にもその言語で検索するよう指示します。
• 複数の文書を対象に表を作成します。 すべての文書または該当箇所に質問を適用し、各セルに出典を示す表としてまとめます。
• すべてローカルで実行でき、追加のモデルアクセスは不要です。 インデックス作成と検索はコンピューター上で実行されます。言語モデルには Claude Code 自体を使うため、2 つ目のモデルや API キーは不要です。
• Claude Code 単体でも、すべての質問に正しく答えられました（8/8 と 4/4）。プラグインを使った場合、442 ページのテストでは最初の実行で 1 件誤答がありました（グラフのラベルが小さすぎて読めなかったため）。ask スキルで修正した後は 4/4 で正解しました。効果は正答率ではなく、労力の軽減にあります。

Claude Code がすぐに読み取れる、小規模で構成の整った文書群では、あまり効果はありません。短い文書 1 件なら、これを使わなくても同じように回答でき、インデックス作成にはフォルダーごとに一度、数分かかります。

インストール

現時点では、Apple silicon 搭載の Mac（macOS、arm64）と、Node.js 18 以降（npx 用）が必要です。

claude plugin marketplace add matthiasnordwig/matrix-mcp
claude plugin install matrix@matrix-mcp

次に claude を起動し（書類のあるフォルダーで起動するのがおすすめです）、書類について Claude に質問するだけです。初回は Claude が Matrix のセットアップを一緒に行います（または /matrix:setup を実行してください）。ほかに読むものはありません。

仕組み

• 書類は、LLM ではなく、それぞれの構造（PDF のレイアウト、見出し、記事、表など）に沿って分割されます（セマンティックチャンク化はデフォルトではありません）。
• 検索では意味とキーワードの両方を使い、条項間の相互参照もたどります。スキャン画像や図表も見つかります。
• 2 つ目の小型モデルが最適な箇所を先頭に並べます（再ランキング、任意：Hugging Face から約 0.6 GB をダウンロードします。ライセンスは Apache-2.0 で、同意後に一度だけダウンロードされます。使わない場合も検索はこれまでどおり動作します）。
• 検索結果はコンパクトです。ファイル名、ページ、アウトラインのパス（書類 › 章 › 条 › 段落）とともに、約 300 文字の抜粋を表示し、同じ記事の結果はまとめられます。引用する前に、Claude は get_chunks で全文を、get_section で記事またはセクション全体を読みます。
• すべての回答にファイル名、ページ、該当箇所が引用され、引用内容は本文と照合されます。
• 複数の書類を対象とする表の作成では、小型モデルを使ったタスクをキュー（llm_tasks / llm_answer）経由で Claude に渡します。タスクは Claude Code のセッション内で実行され、Claude の利用枠を使用します。
• インデックス、モデル、許可されたフォルダーの一覧は ~/Library/Application Support/Matrix MCP に保存されます。Claude が読む該当箇所以外のデータがコンピューターの外に送信されることはありません。
• Matrix は Claude Code の起動元フォルダーを読み取ります。それ以外のフォルダーについては、アクセスの許可を求め（Accept / Decline）、回答を記憶します。
• インデックス化されたフォルダーは同期状態が保たれます。新規ファイルや変更されたファイルは自動で再読み込みされます（起動時と検索前に確認し、頻度は最大で 1 分に 1 回です）。削除されたファイルはコレクションに残り、見つからないものとしてマークされて検索対象から除外されます。ファイルが勝手に削除されることはありません。
• /matrix:status を実行すると、Matrix が保持している情報や処理内容をいつでも確認できます。

使い方

コマンド	内容
/matrix:setup	初回セットアップをガイドします。フォルダー、検索モデル、インデックス作成、質問例を設定できます
/matrix:status	Matrix が保持している情報や処理内容を表示します。コレクション、検索モデル、許可されたフォルダー、待機中のモデルタスク、実行中のジョブを確認できます
/matrix:index <folder>	フォルダーをコレクションにインデックス化します（スキャン画像や図表を含む PDF、Word、Excel、PowerPoint、Markdown、テキスト、画像）
/matrix:ask <question>	書類をもとに回答し、本文と照合された引用（ファイル名、ページ、該当箇所）を付けます
/matrix:table <question>	複数の書類または該当箇所を対象に同じ質問をし、各セルに出典を付けた表を作成します
/matrix:search-model	検索モデルが推奨日と照らして最新かを確認し、より良いモデルがないか調べます

質問するだけでも構いません。Claude が適切なスキルを選びます。サーバー独自のプロンプトも用意されています（/ を入力して index_and_ask、compare_documents などを探してください）。表の作成では小型モデルを使ったタスクを Claude に渡します（llm_tasks、llm_answer で回答）。タスクが多い場合、Claude は並列サブエージェントを使って回答できます。 タスクは、ほかの依頼と同じように Claude Code のセッション内で実行されます。Claude は最初にタスク数を伝えます。

詳細

フォルダー。 Matrix は、Claude Code を起動したフォルダーを読み取ります。それ以外のフォルダーについては、最初に確認し（許可／拒否）、回答を取り消す（Claude に取り消しを依頼する）まで、その回答を保持します。/、ホームフォルダー全体、システムフォルダー、ホームフォルダー内の隠しフォルダー、~/Library を読み取ることはなく、ファイルを変更または削除することもありません。確認なしでフォルダーを常に許可するには、インストール時に設定します（複数指定する場合はカンマで区切ります。フォルダー名にカンマは使用できません）。Claude Code 2.1.222 には /plugin 内に設定画面がありません。

claude plugin install matrix@matrix-mcp --config folders=/path/one,/path/two

設定を変更した後は、Claude Code を再起動してください。同じ方法で --config embedding_model=... と --config embedding_api_key=... も設定できます。存在しないフォルダー、または読み取りできないフォルダーは名前で報告されます （/matrix:status）。macOS では、書類、デスクトップ、ダウンロードのプライバシー保護が原因の場合があります。 「システム設定 › プライバシーとセキュリティ › ファイルとフォルダー」で、Claude Code を実行するアプリに許可を与えてください。インデックス フォルダー ~/Library/Application Support/Matrix MCP は存在するか作成可能で、読み取りと書き込みができる必要があります。 Claude Code の実行中に削除しないでください。

検索モデル。 embeddinggemma-2（多言語対応で、グラフやスキャン画像も検索できます）のままにしてください。初めて必要になったとき、Claude はサイズ（約 1.2 GB、Hugging Face から一度だけ）を知らせ、ダウンロード前に確認します。 代替モデル：embeddinggemma-2-q4（0.2 GB、テキストのみ）、onnx-folder:/path（すでにお持ちのモデル）、 endpoint:https://host/v1#model（独自の埋め込みサービス。API キーはシステムキーチェーンに保存されます）。

再ランキング。 検索モデルの後、Claude は再ランキングモデル（bge-reranker-v2-m3、int8、 約 0.6 GB、Hugging Face から、ライセンスは Apache-2.0）のダウンロードを一度だけ提案し、同意した場合にのみ実行します。関連度に基づいて最初の 20 件の候補を並べ替えます。Apple シリコン搭載 Mac では、検索ごとに約 4 秒かかります。拒否した場合、またはインストールされていない場合は、これまでどおり検索が実行されます。 Claude Code は npx -y @matthiasnordwig/[email protected] でサーバーを起動します。npm はプログラムを一度だけ取得します （約 21 MB、インストールスクリプトなし）。Claude Desktop 向けには、各 リリースにも、デスクトップ拡張機能として同じプログラムを収録した matrix-standalone.mcpb が含まれています。

読み取りツールを一度だけ許可する。 読み取りのたびに Claude Code が確認するのを防ぐには、settings.json（~/.claude/settings.json、またはプロジェクト内の .claude/settings.json）の permissions.allow リストに次を追加します。ここにはインデックスを読み取るだけで、何も変更しないツールのみを記載しています。mcp__plugin_matrix_matrix-standalone__* のようなワイルドカードも使用できますが、 フォルダーの読み取りやモデルのダウンロードも許可されるため、ここでは使用しません。

{
  "permissions": {
    "allow": [
      "mcp__plugin_matrix_matrix-standalone__find_citing_chunks",
      "mcp__plugin_matrix_matrix-standalone__get_chunks",
      "mcp__plugin_matrix_matrix-standalone__get_page_image",
      "mcp__plugin_matrix_matrix-standalone__get_section",
      "mcp__plugin_matrix_matrix-standalone__get_status",
      "mcp__plugin_matrix_matrix-standalone__grid_results",
      "mcp__plugin_matrix_matrix-standalone__job_status",
      "mcp__plugin_matrix_matrix-standalone__list_allowed_folders",
      "mcp__plugin_matrix_matrix-standalone__list_contexts",
      "mcp__plugin_matrix_matrix-standalone__list_documents",
      "mcp__plugin_matrix_matrix-standalone__list_grid_profiles",
      "mcp__plugin_matrix_matrix-standalone__list_grid_runs",
      "mcp__plugin_matrix_matrix-standalone__list_norm_references",
      "mcp__plugin_matrix_matrix-standalone__list_profiles",
      "mcp__plugin_matrix_matrix-standalone__list_sheet_tables",
      "mcp__plugin_matrix_matrix-standalone__lookup_exact",
      "mcp__plugin_matrix_matrix-standalone__page_image_status",
      "mcp__plugin_matrix_matrix-standalone__query_table",
      "mcp__plugin_matrix_matrix-standalone__search_context",
      "mcp__plugin_matrix_matrix-standalone__verify_citations"
    ]
  }
}

意図的にリストに含めていないもの：setup_embedding_model（ダウンロード）、add_files（フォルダーを読み取ります）、search_embedding_models （検索語を使って Hugging Face に問い合わせます）、および何かを作成または変更するすべてのツールです。

利用規約

Matrix は claude を起動せず、Claude の認証情報を読み取ることも、ほかの誰かにサービスを提供することもありません。モデルのタスクには、プログラムを起動した Claude Code セッションが、そのセッション内で、あなたの代わりに回答します。これにより、プラグインは Claude Code の利用規約に準拠します。この規約では、プランの認証情報を使ってほかのリクエストを中継することは認められていません。

ダウンロードツールを事前承認しないでください。 検索モデルのダウンロードに同意することは、ツール呼び出し setup_embedding_model を承認することになります。そのツールや、このサーバーのすべてのツールを常に許可するリストに追加しないでください。また、ツール呼び出しを自動承認するモードでセッションを実行しないでください。

プライバシーポリシー

全文：PRIVACY.md（https://github.com/matthiasnordwig/matrix-mcp/blob/main/PRIVACY.md）。

要約すると、すべての処理はお使いのコンピューター上で行われ、開発者が受け取る情報はありません（テレメトリーやアップデート確認もありません）。ドキュメントがお使いのコンピューターから外部に送信されるのは、ツールを通じてClaudeが読み取る抜粋（Anthropicの規約に基づき、ほかのツールの結果と同様にClaudeが処理します）、設定した場合のお使いの埋め込みエンドポイント、そして同意後にHugging Faceから検索モデルを一度ダウンロードするときだけです。お問い合わせ先： https://github.com/matthiasnordwig/matrix-mcp/issues。

ライセンス

LICENSEを参照してください。