mcp-local-rag

MCP Local RAG

English | 简体中文 | Deutsch | Español | Português (Brasil) | Français

通过 MCP 客户端或终端搜索私人文档，无需将文档发送到嵌入 API。

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 将搜索结果限制在某个路径前缀下；重复使用该选项可纳入多个前缀。

--db-path、--cache-dir 和 --model-name 等全局选项必须放在子命令之前。子命令选项则放在子命令之后：

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

运行 npx mcp-local-rag --help 查看完整的命令参考。

query 会以 JSON 格式将结果写入 stdout，并按最佳匹配优先排序，因此可以通过管道传递给其他工具。各字段的说明见 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 及其他已迁移的路径，然后重启客户端。

Agent 技能

Agent 技能为 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 指定的命令会发起网络请求，否则文档处理和搜索不会发起网络请求。
• 此服务面向单一本地用户设计，不提供身份验证或访问控制。
• 不要让多个 CLI 或 MCP 写入程序同时操作同一个 DB_PATH。同步期间可以执行只读查询。
• 重新摄取时，如果模型和设置相同，则可对未更改的文本复用已保存的嵌入，从而避免重复计算。缓存存储在 DB_PATH/embedding-cache 中。删除缓存不会影响索引的搜索功能，但之后摄取时会重新计算这些嵌入。
• 仅当没有写入操作正在进行时，才能通过复制 DB_PATH 目录来备份索引。

确保文件路径位于某个已配置的根目录下（BASE_DIR、任何 BASE_DIRS 条目或任何 CLI --base-dir）。使用绝对路径。

“BASE_DIRS 必须是 JSON 数组……”

BASE_DIRS 接受一个包含一个或多个非空路径字符串的 JSON 数组：

• 有效：BASE_DIRS='["/Users/me/work","/Users/me/specs"]'
• 无效：BASE_DIRS=/a:/b（不支持分隔符语法）
• 无效：BASE_DIRS='[]'（数组为空）

MCP 客户端看不到工具

1. 检查配置文件语法
2. 完全重启客户端（在 Mac 上按 Cmd+Q 退出 Cursor）
3. 直接测试：npx mcp-local-rag 应能无错误运行

贡献

欢迎贡献！有关设置和指南，请参阅 CONTRIBUTING.md。

许可证

MIT 许可证。可免费用于个人和商业用途。

博客文章

• 构建用于 Agent 编码的本地 RAG：深入介绍语义分块和混合搜索的设计。

致谢

基于 Anthropic 的 Model Context Protocol、 LanceDB 和 Transformers.js 构建。