/ 目录 / 演练场 / 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. 细化搜索
    只给我与'环形注意力'最相关的前 5 个段落,原始内容 — 不要总结。✓ 已复制
    → 排序的段落列表

结果: 你曾经下载的每一篇论文现在都可以按主题查询 — 你的阅读生活的永久升级。

注意事项
  • 扫描的 PDF 没有可提取的文本 — 在摄取之前先运行 OCR 处理(ocrmypdf)
  • 首次索引 1000+ 文件时速度很慢(CPU embeddings) — 让它在一夜之间运行;增量重新摄取很快
搭配使用: filesystem

在不泄露到任何云端的情况下查询机密合同 / HR 文档

👤 法务、人力资源、合规 ⏱ ~20 min intermediate

何时使用: 文档太敏感了,无法使用 OpenAI/Claude 云 embeddings。你需要搜索但无法将内容发送到任何地方。

步骤
  1. 摄取
    将 /secure/contracts/*.pdf 摄取到 local-rag。✓ 已复制
    → 文件在本地索引;确认没有网络调用
  2. 查询
    哪些合同有超过 12 个月的自动续约条款?✓ 已复制
    → 候选合同列表,以及引用的条款

结果: 可搜索的私有语料库,数据不离开你的机器。

注意事项
  • Claude 的答案仍然会发送给 Anthropic — embeddings 是本地的,但对话不是 — 如果答案也必须是本地的,通过 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 作为源将其摄取到 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 数
查询结果 500-3000 个 token,取决于 top_k
费用
免费。一次性约 90MB 模型下载。
提示
对大多数问题将 top_k 设置为 5-8;更高的值浪费 token 而不会改进答案。

安全

权限、密钥、影响范围

凭据存储: 无 — 无 API 密钥
数据出站: 模型下载后零。你的文档永不离开你的机器。

故障排查

常见错误与修复

第一个查询很慢 / 似乎挂起

Embedding 模型正在首次运行时下载(约 90MB)。后续调用很快。

验证: Check ~/.cache/mcp-local-rag for the model file
PDF 摄取返回 0 个块

PDF 可能被扫描(仅图像)。首先运行 ocrmypdf input.pdf output.pdf

验证: pdftotext input.pdf -
结果似乎不相关

纯语义搜索在短查询时困难。添加更多关键词。混合搜索已经加强了它们。

处理大型 PDF 时内存不足

首先分割 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 文件上传文档集较小(<20 个文件)且你使用托管聊天不是 MCP;无法被脚本化

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills