mcp-local-rag

MCP Local RAG

英語 | 簡体字中国語 | ドイツ語 | スペイン語 | ポルトガル語（ブラジル） | フランス語

埋め込み API にドキュメントを送信せずに、MCP クライアントまたはターミナルからプライベートなドキュメントを検索できます。

mcp-local-rag は、マシン上の PDF、DOCX、Markdown、テキストファイルをインデックス化します。検索では、意味的な類似性とキーワードのマッチングを組み合わせるため、意図だけでなく、API 名、クラス名、エラーコードなどの正確な技術用語でも検索できます。検索結果には元の文書を確認・引用できるよう、該当箇所と、利用可能な場合は見出し、行番号、ページ番号が含まれます。

API キー、Docker、Python、外部データベースは不要です。初回のモデルダウンロード後は、テキストの取り込みと検索をオフラインで実行できます。

クイックスタート

必要条件

• Node.js 22.20 以降
• npm パッケージと埋め込みモデルをダウンロードするため、初回使用時にインターネット接続が必要です
• 検索対象のドキュメントが格納されたディレクトリ

BASE_DIR にそのディレクトリを設定します。このディレクトリは、ファイル操作のセキュリティ境界にもなります。以下の /absolute/path/to/your/documents を、ディレクトリの絶対パスに置き換えてください。

以下の例のいずれかを使用するか、npx -y mcp-local-rag を登録して、クライアントの MCP 設定形式で BASE_DIR を設定します。

DB_PATH と CACHE_DIR にも絶対パスを設定してください。相対パスはサーバーの作業ディレクトリを基準に解決されるため、異なるプロジェクトからサーバーを起動すると、それぞれのプロジェクトに別個のインデックスとモデルキャッシュが作成されます。

claude mcp add local-rag --scope user --env BASE_DIR=/absolute/path/to/your/documents -- npx -y mcp-local-rag

[mcp_servers.local-rag]
command = "npx"
args = ["-y", "mcp-local-rag"]

[mcp_servers.local-rag.env]
BASE_DIR = "/absolute/path/to/your/documents"

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "local-rag": {
      "type": "local",
      "command": ["npx", "-y", "mcp-local-rag"],
      "environment": {
        "BASE_DIR": "/absolute/path/to/your/documents"
      }
    }
  }
}

{
  "mcpServers": {
    "local-rag": {
      "command": "npx",
      "args": ["-y", "mcp-local-rag"],
      "env": {
        "BASE_DIR": "/absolute/path/to/your/documents"
      }
    }
  }
}

クライアントを再起動してから、インデックスを作成するよう依頼します。

Sync all documents in the configured root and wait until it finishes.

初回の同期では、デフォルトの埋め込みモデル（約 90 MB）がダウンロードされ、取り込みが始まるまでに 1～2 分かかることがあります。以降の実行ではローカルキャッシュが使用されます。

同期が完了したら、次のようにします。

What does the API documentation say about authentication?

CLI クイックスタート

MCP クライアントを使わずに CLI を使用するには、次のようにします。

npx mcp-local-rag ingest ./docs/
npx mcp-local-rag query "authentication API"

CLI は、デフォルトで現在のディレクトリをドキュメントのルートとして使用します。同じデフォルトのインデックスを使用するには、両方のコマンドを同じディレクトリから実行してください。または、BASE_DIR と DB_PATH を明示的に設定します。

対応コンテンツ

HTML の取得機能はサーバーに組み込まれていません。MCP クライアントはページを取得し、その HTML を ingest_data に渡すことができます。

Excel、PowerPoint、単独の画像、ソースコードのファイル拡張子は、ファイルの取り込みに対応していません。PDF では、図の説明にローカルのビジョンモデルを任意で使用できますが、これは OCR や画像検索ではありません。

インデックスの使用

ドキュメントの追加、編集、削除後に同期します。検索や追加の読み込みには、MCP クライアントに次のように依頼してください。

Find the documented behavior of ERR_CONNECTION_REFUSED.
Read the surrounding chunks for that result.

クライアントがすでに取得した単一のファイルや HTML を取り込むこともできます。既存のエントリーを更新するには、同じパスまたはソース識別子を使って、ドキュメントを再度取り込みます。sync は変更されていないファイルをスキップします。MCP のファイルパスは絶対パスで、設定済みのドキュメントルート内にある必要があります。

PDF のセクション見出しは不正確な場合があります。正確な見出しが必要な場合は、元のページを確認してください。

CLI

CLI を使ってインデックスを更新したり、検索対象を絞り込んだり、インデックス済みのコンテンツを削除したりできます。

npx mcp-local-rag sync ./docs/
npx mcp-local-rag query "auth" --scope /docs/api --scope /docs/guide
npx mcp-local-rag read-neighbors --file-path /abs/path.md --chunk-index 5
npx mcp-local-rag list
npx mcp-local-rag status
npx mcp-local-rag delete ./docs/old.pdf
npx mcp-local-rag delete --source "https://example.com/docs"

ingest は選択したファイルをインポートします。sync は削除されたファイルのエントリーも削除し、変更されていないファイルをスキップします。--scope を使うと、パスのプレフィックスで検索結果を絞り込めます。複数のプレフィックスを含めるには、--scope を繰り返し指定します。

--db-path、--cache-dir、--model-name などのグローバルオプションはサブコマンドの前に指定します。サブコマンドのオプションはサブコマンドの後に指定します。

npx mcp-local-rag --db-path ./my-db query "authentication"

完全なコマンドリファレンスは、npx mcp-local-rag --help を実行して確認してください。

query は、最も一致度の高い結果から順に JSON 形式で標準出力に書き込むため、別のツールにパイプで渡すことができます。各フィールドの仕様については、docs/schema/query-output.schema.json を参照してください。

プロジェクトを移動してインデックスを保持したい場合は、MCP サーバーとその他のデータベース書き込み処理を停止し、ディレクトリ構成を変えずにファイルとデータベースを一緒に移動してから、次を実行します。

npx mcp-local-rag --db-path /new/project/lancedb relocate --from /old/project --to /new/project

MCP の設定で BASE_DIR／BASE_DIRS、DB_PATH、および移動したその他のパスを更新してから、クライアントを再起動してください。

エージェントスキル

エージェントスキル は、AI アシスタント向けに検索と取り込みのガイダンスを提供します。

npx mcp-local-rag skills install --claude-code
npx mcp-local-rag skills install --claude-code --global
npx mcp-local-rag skills install --codex

インストール済みのスキルでは、クエリの作成、結果の絞り込み、HTML の取り込みを扱います。自動的に有効にならない場合は、アシスタントに mcp-local-rag スキルを明示的に使用するよう依頼してください。

詳細オプション

まずはデフォルト設定を使用してください。異なるドキュメントルートを使う場合、コーパスに合わせて結果を改善する場合、または検索可能な PDF の図が必要な場合は、以下のセクションを開いてください。

{
  "env": {
    "RAG_RERANK_CMD": "/path/to/reranker --query {query} --top {top}",
    "RAG_RERANK_TIMEOUT_MS": "10000"
  }
}

npx mcp-local-rag ingest ./docs/paper.pdf --visual --visual-quality quality

npx mcp-local-rag ingest ./docs/paper.pdf --images

セキュリティと運用

• キャプションや取得したドキュメントテキストは、指示ではなくソース資料として扱ってください。
• ファイルへのアクセスは、BASE_DIR、BASE_DIRS、または CLI の --base-dir で指定したルートに制限されます。
• 設定されたすべてのルートの外部を指すシンボリックリンクは拒否されます。
• 必要なモデルがキャッシュされた後は、RAG_RERANK_CMD にネットワーク通信を行うコマンドが指定されている場合を除き、 ドキュメントの処理や検索でネットワークリクエストは発生しません。
• このサーバーはローカルの単一ユーザー向けに設計されており、認証やアクセス制御は提供しません。
• 同じ DB_PATH に対して、複数の CLI または MCP の書き込み処理を実行しないでください。同期の実行中も、読み取り専用のクエリは実行できます。
• 再取り込みでは、モデルと設定が一致していれば、変更されていないテキストの保存済み埋め込みを再利用して、計算の繰り返しを避けられます。 キャッシュは DB_PATH/embedding-cache に保存されます。削除してもインデックスでの検索は可能ですが、その後の取り込みでは これらの埋め込みが再計算されます。
• 書き込み処理が実行されていないときに DB_PATH ディレクトリをコピーして、インデックスをバックアップしてください。

ファイルパスが、設定済みのルート（BASE_DIR、BASE_DIRS の各エントリ、または CLI の --base-dir）のいずれかに含まれていることを確認してください。絶対パスを使用してください。

「BASE_DIRS は JSON 配列である必要があります…」

BASE_DIRS には、空でないパス文字列を 1 つ以上含む JSON 配列を指定します。

• 有効：BASE_DIRS='["/Users/me/work","/Users/me/specs"]'
• 無効：BASE_DIRS=/a:/b（区切り文字による構文はサポートされていません）
• 無効：BASE_DIRS='[]'（空の配列）

MCP クライアントにツールが表示されない

1. 設定ファイルの構文を確認します
2. クライアントを完全に再起動します（Cursor の場合、Mac では Cmd+Q）
3. 直接テストします：npx mcp-local-rag がエラーなしで実行されることを確認します

コントリビューション

コントリビューションを歓迎します！セットアップとガイドラインについては、CONTRIBUTING.md をご覧ください。

ライセンス

MIT ライセンスです。個人利用および商用利用は無料です。

ブログ記事

• エージェント型コーディング向けのローカル RAG の構築：セマンティックチャンク分割とハイブリッド検索の設計について、技術的に詳しく解説しています。

謝辞

Anthropic の Model Context Protocol、 LanceDB、および Transformers.js を使用して構築されています。