mcp-local-rag MCP — ユースケース, インストール & ライブデモ

なぜ使うのか

主な機能

完全ローカル — エンベディングはデバイス上のモデルで計算され、初回実行後のネットワーク通信はゼロ
ハイブリッド検索：セマンティック（エンベディング）にキーワードマッチングを組み合わせて精度向上
PDF、DOCX、TXT、Markdown、HTMLに対応 — 個人ナレッジでよく使われるフォーマットをカバー
npx mcp-local-rag のワンコマンドでセットアップ完了。CLIとしても利用可能
CPUのみで動作 — 最近のノートPCなら何でもOK

ライブデモ

実際の動作

local-rag.replay ▶ 準備完了

0/0

インストール

クライアントを選択

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "local-rag": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-local-rag"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config を開く。保存後、アプリを再起動。

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "local-rag": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-local-rag"
      ],
      "_inferred": true
    }
  }
}

Cursor は Claude Desktop と同じ mcpServers スキーマを使用。プロジェクト設定はグローバルより優先。

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "local-rag": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-local-rag"
      ],
      "_inferred": true
    }
  }
}

Cline サイドバーの MCP Servers アイコンをクリックし、"Edit Configuration" を選択。

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "local-rag": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-local-rag"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop と同じ形式。Windsurf を再起動して反映。

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "local-rag",
      "command": "npx",
      "args": [
        "-y",
        "mcp-local-rag"
      ]
    }
  ]
}

Continue はマップではなくサーバーオブジェクトの配列を使用。

~/.config/zed/settings.json

{
  "context_servers": {
    "local-rag": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "mcp-local-rag"
        ]
      }
    }
  }
}

context_servers に追加。保存時に Zed がホットリロード。

claude mcp add local-rag -- npx -y mcp-local-rag

ワンライナー。claude mcp list で確認、claude mcp remove で削除。

ユースケース

実用的な使い方： mcp-local-rag

ダウンロードした論文やPDFでプライベートRAGを構築する

👤 研究者、学生、ナレッジワーカー ⏱ ~30 min beginner

使うタイミング： ~/Documents/papers に大量のPDFを溜め込んでいて、実際に活用したいとき — 「あの論文でattention decayについて何て書いてあったっけ？」

前提条件

ディスク上のPDFまたはドキュメント — 任意のフォルダ — 再帰的な取り込みに対応

フロー

フォルダを取り込む

Ingest everything under ~/Documents/papers into local-rag. Skip files larger than 50MB.✓ コピーしました

→ ファイルごとの取り込みログ + 「N件のファイルをインデックス済み」のサマリー
質問する

Across my papers, what do they say about positional encoding in long-context transformers? Cite the source file and page if possible.✓ コピーしました

→ ソースファイルの引用付きで合成された回答
検索を絞り込む

Just give me the top 5 passages most relevant to 'ring attention', raw — don't summarize.✓ コピーしました

→ ランク付けされたパッセージのリスト

結果： これまでダウンロードしたすべての論文がトピック別に検索可能に — 読書体験が恒久的にアップグレードされます。

注意点

スキャンされたPDFにはテキストが抽出できない — 取り込み前にOCR処理を実行する（ocrmypdf）
1000件以上のファイルの初回インデックスは遅い（CPUエンベディング） — 一晩かけて実行すれば完了する。増分の再取り込みは高速

組み合わせ： filesystem

機密契約書やHR文書をクラウドに漏洩させずに検索する

👤 法務、人事、コンプライアンス ⏱ ~20 min intermediate

使うタイミング： OpenAI/Claudeのクラウドエンベディングに送るには機密性が高すぎるドキュメント。検索は必要だが、コンテンツをどこにも送信できない場合。

フロー

取り込む

Ingest /secure/contracts/*.pdf into local-rag.✓ コピーしました

→ ファイルがローカルでインデックスされ、ネットワーク通信が行われていないことを確認
クエリする

Which contracts have an auto-renewal clause longer than 12 months?✓ コピーしました

→ 該当条項を引用した候補契約書のリスト

結果： マシン外にデータが一切出ない、検索可能なプライベートコーパスの完成。

注意点

Claudeの回答自体はAnthropicに送信される — エンベディングはローカルだが会話はそうではない — 回答もローカルにする必要がある場合は、クラウドのClaudeの代わりにOllamaやLM Studio経由でローカルLLMを使用する

組み合わせ： filesystem

コードベースのドキュメントやMarkdownをインデックスし、「これはどこに書いてある？」を即座に検索

👤 大規模リポジトリのエンジニア ⏱ ~15 min beginner

使うタイミング： チームのwiki、設計ドキュメント、ADRがMarkdownファイルに散在しており、grepでは意味で検索できないとき。

フロー

ドキュメントツリーを取り込む

Ingest all .md files under ./docs. Re-ingest when I ask.✓ コピーしました

→ インデックスされたファイルのリスト
アーキテクチャに関する質問をする

Where's the rationale for using event sourcing instead of CRUD? I remember an ADR about it.✓ コピーしました

→ 該当するADRファイルへのポインタ + 根拠の引用

結果： ファイル名ではなくコンセプトで検索できるチームナレッジの実現。

注意点

ドキュメントが陳腐化する — 古いADRが現在の状態と矛盾する — 重要な検索の前に再取り込みを実行する。非推奨のドキュメントはdelete_fileで削除する

組み合わせ： filesystem

組み合わせ

他のMCPと組み合わせて10倍の力を

local-rag + filesystem

フォルダを監視し、ファイルが変更されたら再取り込みする

Every time a file under ~/Notes changes, re-ingest it into local-rag.✓ コピーしました

local-rag + firecrawl

ドキュメントサイトをスクレイピングし、local-ragに取り込んでオフライン検索する

Crawl docs.example.com, save each page as Markdown, then ingest all of them into local-rag.✓ コピーしました

local-rag + playwright

JSレンダリングされたページをキャプチャし、抽出テキストを取り込む

Open this SPA, grab the rendered HTML, ingest_data it into local-rag with the URL as source.✓ コピーしました

ツール

このMCPが提供する機能

ツール	入力	呼び出すタイミング	コスト
ingest_file	path: str \| path[]	1つまたは複数のファイルをインデックスに追加する	CPU only
ingest_data	html: str, source_url?: str	生のHTMLデータを追加する — スクレイピング後に便利	CPU only
query_documents	query: str, top_k?: int	メインの検索呼び出し — ユーザーの質問に回答する前に使用する	free
list_files		インデックス済みのファイルを確認する	free
delete_file	path: str	古い・不要なファイルをインデックスから削除する	free
status		インデックスサイズの健全性チェック	free

コストと制限

運用コスト

APIクォータ: なし — すべてローカル
呼び出しあたりのトークン: クエリ結果はtop_kに応じて500〜3000トークン
金額: 無料。初回のみ約90MBのモデルダウンロードが必要です。
ヒント: ほとんどの質問ではtop_kを5〜8に設定してください。それ以上に増やしてもトークンを消費するだけで回答の品質は向上しません。

セキュリティ

権限、シークレット、影響範囲

認証情報の保管： なし — APIキー不要

データ送信先： モデルダウンロード後のデータ送信はゼロ。ドキュメントが端末外に出ることはありません。

シングルユーザー設計 — マルチユーザーの分離機能なし。インデックスディレクトリを共有しないでください。
エンベディングモデルを変更する場合、DBを削除してすべて再取り込みする必要があります。

トラブルシューティング

よくあるエラーと対処法

初回クエリが遅い／フリーズしたように見える

初回実行時にエンベディングモデルをダウンロード中です（約90MB）。以降の呼び出しは高速です。

確認： Check ~/.cache/mcp-local-rag for the model file

PDFの取り込みで0チャンクが返される

PDFがスキャン画像のみの可能性があります。先にocrmypdf input.pdf output.pdfを実行してください。

確認： pdftotext input.pdf -

検索結果が的外れに感じる

純粋なセマンティック検索は短いクエリが苦手です。キーワードを追加してください。ハイブリッド検索が自動的にキーワードをブーストします。

大きなPDFでOut of Memoryが発生する

先にPDFを分割するか、Nodeのヒープサイズを増やしてください：NODE_OPTIONS=--max-old-space-size=8192

代替案

mcp-local-rag 他との比較

代替案	代わりに使う場面	トレードオフ
Chroma MCP / Qdrant MCP	マルチユーザー対応、スケーリング、メタデータフィルターを備えた本格的なベクトルDBが必要な場合	セットアップが複雑で、通常はサーバーの常時稼働が必要
OpenAI Assistants file_search	ドキュメントをOpenAIのクラウドに送信しても問題ない場合	ローカルではなくトークン課金が発生するが、セットアップ不要で精度が高い
ChatGPT Projects / Claude Projects file upload	少量のドキュメント（20ファイル未満）で、ホスト型チャットを使用している場合	MCPではないため、スクリプトによる自動化ができない

その他

リソース

📖 GitHub の公式 README を読む

🐙 オープンな issue を見る

🔍 400以上のMCPサーバーとSkillsを見る