/ 目錄 / 演練場 / mcp-local-rag
● 社群 shinpr ⚡ 即開即用

mcp-local-rag

作者 shinpr · shinpr/mcp-local-rag

私密、本機優先的 RAG — 將你的 PDF、文件和程式碼建立索引一次,即可從任何 MCP 客戶端進行語意搜尋。無需 API 金鑰、無需雲端、資料不離開你的機器。

mcp-local-rag 在下載約 90MB 的模型後完全離線運作。支援匯入 PDF/DOCX/TXT/MD/HTML 檔案或原始 HTML 字串,並以語意搜尋結合關鍵字搜尋進行查詢。非常適合個人知識庫、機密文件,以及在飛機上離線工作。

為什麼要用

核心特性

即時演示

實際使用效果

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,想真正善加利用它們——「那篇論文對注意力衰減有什麼看法?」

前置條件
  • 磁碟上的 PDF 或文件 — 任何檔案資料夾——支援遞迴匯入
步驟
  1. 匯入資料夾
    將 ~/Documents/papers 下的所有檔案匯入 local-rag,略過大於 50MB 的檔案。✓ 已複製
    → 逐檔匯入記錄 + 「已建立索引 N 個檔案」摘要
  2. 提問查詢
    在我的所有論文中,它們對長語境 Transformer 中的位置編碼有什麼看法?盡可能標註來源檔案與頁碼。✓ 已複製
    → 附有來源檔案引用的綜合性回答
  3. 精煉搜尋
    直接給我與「ring attention」最相關的前 5 段原文,不需摘要。✓ 已複製
    → 依相關度排序的段落列表

結果: 你曾下載的每一篇論文現在都可依主題查詢——永久提升你的閱讀生活。

注意事項
  • 掃描版 PDF 無法擷取文字 — 匯入前先執行 OCR(ocrmypdf)
  • 首次建立 1000+ 個檔案的索引速度很慢(CPU 嵌入計算) — 讓它整晚跑完;增量重新匯入速度很快
搭配使用: filesystem

查詢機密合約/人資文件,且不洩漏至任何雲端

👤 法務運營、人資、合規人員 ⏱ ~20 min intermediate

何時使用: 文件太敏感,不適合使用 OpenAI/Claude 雲端嵌入服務。你需要搜尋功能,但不能將內容傳送至任何地方。

步驟
  1. 匯入
    將 /secure/contracts/*.pdf 匯入 local-rag。✓ 已複製
    → 檔案已在本機建立索引;確認未發出任何網路請求
  2. 查詢
    哪些合約包含超過 12 個月的自動續約條款?✓ 已複製
    → 附有條款引文的候選合約清單

結果: 可搜尋的私人語料庫,資料完全不離開機器。

注意事項
  • Claude 的回答仍會傳送至 Anthropic——嵌入是本機的,但對話不是 — 若回答也必須保持本機,請改用 Ollama 或 LM Studio 搭配本機 LLM,而非雲端 Claude
搭配使用: filesystem

組合

與其他 MCP 搭配,撬動十倍槓桿

local-rag + filesystem

監控資料夾,當檔案變更時重新匯入

每當 ~/Notes 下有檔案變更時,將其重新匯入 local-rag。✓ 已複製
local-rag + firecrawl

爬取文件網站後匯入 local-rag 以供離線查詢

爬取 docs.example.com,將每個頁面儲存為 Markdown,然後全部匯入 local-rag。✓ 已複製
local-rag + playwright

擷取 JS 渲染的頁面並匯入其擷取的文字

開啟這個 SPA,取得渲染後的 HTML,以 URL 為來源將其 ingest_data 至 local-rag。✓ 已複製

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
ingest_file path: str | path[] 將一個或多個檔案新增至索引 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 配額
無 — 全部本機
每次呼叫 Token 數
查詢結果依 top_k 不同,約 500-3000 tokens
費用
免費。一次性下載約 90MB 的模型。
提示
大多數問題將 top_k 設為 5-8 即可;設定更高只會浪費 tokens,不會改善回答品質。

安全

權限、密鑰、影響範圍

憑證儲存: 無 — 不需要 API 金鑰
資料出站: 模型下載後零資料外傳。你的文件永遠不會離開機器。

故障排查

常見錯誤與修復

First query is slow / seems to hang

首次執行時正在下載嵌入模型(約 90MB),後續呼叫速度很快。

驗證: Check ~/.cache/mcp-local-rag for the model file
PDF ingest returns 0 chunks

PDF 可能是掃描版(僅含圖片)。請先執行 ocrmypdf input.pdf output.pdf

驗證: pdftotext input.pdf -
Results feel irrelevant

純語意搜尋對短查詢效果較差。請加入更多關鍵字,混合搜尋已會對其加權。

Out of memory on large PDFs

先將 PDF 分割,或提高 Node 堆疊大小:NODE_OPTIONS=--max-old-space-size=8192

替代方案

mcp-local-rag 對比其他方案

替代方案何時用它替代權衡
Chroma MCP / Qdrant MCP你需要真正的向量資料庫,具備多使用者、擴充性與中繼資料過濾功能設定較複雜,通常需要啟動一個伺服器
OpenAI Assistants file_search你可以接受將文件傳送至 OpenAI 的雲端非本機,依 token 計費,但零設定且準確度更高
ChatGPT Projects / Claude Projects file upload文件數量少(不超過 20 個檔案)且你使用託管式聊天介面非 MCP;無法以程式腳本操作

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills