本地文档 RAG 如何通过 MCP 接入 Claude Code？

作者：袖梨 2026-09-13

本地文档 RAG 可以通过 Local Knowledge RAG MCP Server 接入 Claude Code：项目目录中的 Markdown 与文本文件先被切分和向量化，嵌入写入 PostgreSQL 的 pgvector 扩展；Claude Code 再通过 MCP 调用语义搜索、获取详细结果并生成带本地文件位置的报告。这样知识源仍是磁盘文件，搜索结果可以回到 VS Code 中的原文行，而不是停留在无法定位的知识库片段。

最小部署由四部分组成：Node.js MCP 服务、PostgreSQL 与 pgvector、一个嵌入模型提供方，以及 Claude Code。敏感文档可选 Ollama 在本机生成嵌入；也可使用 OpenAI 或兼容接口。安装时应先用无敏感样例建立索引，验证包含与排除规则、工作区隔离和引用跳转，再逐步纳入正式文档。

Local Knowledge RAG MCP 解决什么问题

传统 RAG 平台通常要求手工上传文档，原文件更新后还要再次导入。返回的引用常指向平台内部资源，开发者在 IDE 中无法直接打开对应源码或文档行。这个项目把本地目录作为知识源，索引只是可重建的检索层。

用户可以在 Claude Code 中用自然语言搜索文档，服务端通过向量相似度选出片段，保存一次搜索会话，再按模板生成 Markdown 报告。结果携带文件路径和行号，VS Code 可以直接定位原文。

它适合技术文档、研究笔记、规范、项目设计和大量 Markdown 资料。它不是聊天记忆系统，也不会自动判断一条事实是否仍有效。RAG 找到的是语义相关内容，最终结论仍需读取来源和检查版本。

整体数据流

索引阶段先扫描当前工作区中符合规则的文件，按文本结构切成片段，调用嵌入模型生成向量，再把向量、内容摘要、路径、行号和工作区标识写入 PostgreSQL。HNSW 索引用于近似最近邻搜索。

查询阶段由 Claude Code 调用 `search_knowledge`。服务器把问题转换为向量，在当前工作区范围内检索相似片段并创建搜索会话。后续可以用 `get_search_results` 读取详细结果，或用 `create_rag_report` 按模板生成报告。

原始文档仍留在磁盘，PostgreSQL 中的向量和缓存可以重建。修改文件后要执行增量更新；更换嵌入模型后必须完整重建，因为不同模型产生的向量空间不能混用。

准备运行环境

需要 Node.js 与 npm、Git、Claude Code，以及可用的 PostgreSQL pgvector 实例。若选择 Ollama，还需要安装并下载嵌入模型。先确认端口 5432 未被其他数据库占用，并为本项目创建独立数据库和账户。

官方快速开始使用 Docker 运行 pgvector。示例密码只适合本机实验，正式使用必须替换为随机密码，数据库端口最好只绑定回环地址或不向宿主机外部开放。

docker run -d 
  --name local-knowledge-rag-db 
  -e POSTGRES_DB=local_knowledge_rag 
  -e POSTGRES_USER=rag_user 
  -e POSTGRES_PASSWORD=replace-with-random-password 
  -p 127.0.0.1:5432:5432 
  -v local-knowledge-rag-data:/var/lib/postgresql/data 
  --restart unless-stopped 
  ankane/pgvector

生产环境应固定经过审核的镜像版本，而不是长期跟随浮动标签。数据库卷需要备份，但备份不能替代原始文档备份；二者恢复目标不同。

克隆、安装和构建

从项目仓库克隆源码，安装依赖并生成 `dist` 目录。构建失败时先检查项目要求的 Node.js 版本、锁文件与 TypeScript 编译输出，不要删除锁文件后盲目升级全部依赖。

git clone REPOSITORY_URL
cd local-knowledge-rag-mcp
npm install
npm run build

完成后确认 `dist/mcp-server.js` 存在。可以先运行帮助或启动命令观察标准错误输出，但 MCP 的标准输出用于 JSON-RPC，不能混入普通调试日志。

安装目录应与被索引工作区分开。不要把服务器自己的 `node_modules`、构建产物和日志误纳入知识库。

配置数据库连接

复制 `.env.example` 为 `.env`，配置 DATABASE_URL。`.env` 包含数据库密码和可能的嵌入 API Key，必须进入 `.gitignore`，文件权限应限制为当前用户读取。

DATABASE_URL=postgresql://rag_user:password@localhost:5432/local_knowledge_rag

先用数据库客户端测试连接，再启动 MCP。连接被拒绝通常来自容器未运行、端口映射错误或密码不一致；出现 pgvector 类型错误时，检查扩展是否安装和初始化。

多个工作区可以共用同一 DATABASE_URL，项目按工作区绝对路径隔离索引，并用 PostgreSQL advisory lock 保护并发更新。移动目录会改变绝对路径身份，应重新确认索引，而不是假设旧数据自动迁移。

选择嵌入模型

项目支持 OpenAI、Ollama、LiteLLM 和 OpenAI 兼容 API。选择标准应包括文档语言、隐私、速度、向量维度、成本和离线要求。中文资料必须用真实查询评估召回，不要只看英文基准。

使用云端嵌入意味着文档片段会发送给对应提供方。即使原文件留在本地，也不能称为完全离线。敏感资料可使用 Ollama，并把服务限制在回环地址。

OLLAMA_BASE_URL=OLLAMA_OPENAI_COMPATIBLE_ENDPOINT
EMBEDDING_MODEL=nomic-embed-text

使用 OpenAI 或兼容服务时，在 `.env` 中保存专用低权限密钥，不要把密钥写进 Claude 的 MCP 配置。官方项目会自动加载 `.env`，减少密钥在多个文件中复制。

配置纳入和排除规则

默认索引 Markdown 与纯文本文件。通过 `RAG_INCLUDE_PATTERNS` 与 `RAG_EXCLUDE_PATTERNS` 控制范围。应排除 `.git`、依赖目录、构建输出、临时文件、密钥、数据库转储和机器生成的大日志。

第一轮只索引一个小型 docs 目录，检查统计和搜索结果后再扩大。不要直接把整个用户主目录当作工作区。文件名和路径本身也可能泄露敏感项目，即使正文没有被命中。

规则变更后执行索引更新，并验证之前排除的文件不再出现在结果中。若敏感内容曾经进入向量库，仅修改排除规则可能不会清理旧片段，应按项目工具说明重建索引并检查数据库。

把 MCP 注册到 Claude Code

构建成功后，可以把服务注册为用户级或项目级 MCP。个人所有项目都需要同一知识库时使用 user scope；只服务当前仓库时采用项目范围，更容易控制暴露面。

claude mcp add -s user local-knowledge-rag -- 
  node /absolute/path/to/local-knowledge-rag-mcp/dist/mcp-server.js

项目级配置则先进入目标工作区，再执行不带 user scope 的添加命令。所有路径使用绝对路径，避免 Claude Code 从不同当前目录启动时找不到脚本。

重新启动 Claude Code 后检查 MCP 状态和工具列表。连接成功只说明进程能启动，还要调用 `index_status` 与 `list_search_results` 验证数据库和工作区上下文。

第一次建立索引

在 Claude Code 中请求“打开 Index Manager”，服务会启动本机 Web 管理界面。该界面默认绑定回环地址的 3456 端口或下一个可用端口，并显示索引进度、文件数量和当前文件。

点击 Update Index 建立或增量更新索引。初次运行先观察文件清单是否符合规则，再等待完成。管理界面没有面向公网的认证，设计目标是可信本地开发环境，不能通过隧道或反向代理公开。

进度卡住时查看系统临时目录中的工作区日志。磁盘空间、数据库连接、嵌入服务限流和损坏文件都可能导致中断。不要在不知道原因时反复点击完整重建。

执行第一次语义搜索

索引完成后，让 Claude 搜索一个样例文档中确实存在、但措辞不同的概念。语义检索应能找到相关片段，而精确术语搜索可作为对照。要求返回文件路径、行号、相似度和短片段。

然后打开引用位置，核对原文是否支持回答。RAG 输出是候选证据，不是答案本身。相似度低或来源冲突时，Claude 应继续检索或说明不确定，而不是补全不存在的事实。

默认结果数和最低相似度只是起点。结果太少先检查索引和查询表达，再适度降低阈值；噪声太多则提高阈值、缩小目录或改进文档结构。

MCP 工具有哪些职责

`search_knowledge` 负责语义检索并建立会话，`get_search_results` 获取详细结果，`list_search_results` 查看缓存会话，`create_rag_report` 根据结果生成 Markdown 报告。

`rebuild_index` 执行完整重建，`cancel_index_generation` 取消正在运行的任务，`index_status` 返回进度。`reload_config` 重新加载部分配置，`open_index_manager` 打开管理界面。

`reinitialize_schema` 会重置工作区数据，属于破坏性操作。不要把它当作普通故障排查按钮；执行前确认目标工作区和备份，并确保没有其他索引任务。

生成可核验的报告

搜索后可以使用 basic、paper、bullet_points 或 manual 模板生成报告，默认写入 `rag-reports`。模板定义输出结构，不改变检索证据。自定义模板应要求每个关键结论保留来源位置。

报告目录也可能被默认文件规则再次索引，造成模型检索到自己的摘要而不是原文。应明确把 `rag-reports` 排除，或把报告放在工作区之外。

生成后检查文件 diff、引用和编码。报告适合成为草稿，不应未经审阅替代原始技术文档。

VS Code 行号跳转为何重要

普通 RAG 引用常指向内部文档 ID，开发者还要手动寻找原文件。项目返回本地路径与行号，可在 VS Code 中直接打开匹配位置。最小 VS Code 扩展还提供 QuickPick 搜索框，方向键预览结果，回车打开目标行。

安装扩展时可以把仓库中的目录链接到 VS Code 扩展目录，或打包为 VSIX。若 VS Code 找不到 `lkrag`，通常是图形应用继承的 PATH 与终端不同，应显式配置可执行文件绝对路径。

文件被大幅编辑后，旧索引中的行号可能漂移。索引更新和引用验证必须成为日常流程，不能把旧行号当作永久标识。

CLI 适合自动化索引

构建后可通过 npm link 安装 `lkrag`。CLI 支持 search、update-index、rebuild-index 和 status，并可输出 plain、TSV 或 JSON，适合编辑器、脚本和定时任务。

lkrag update-index --workspace-path /absolute/path/to/docs
lkrag search "authentication flow" 
  --workspace-path /absolute/path/to/docs 
  --format json --limit 10
lkrag status

定时更新前先确认文件变更频率和嵌入成本。高频扫描不一定提高有效性，反而可能与手工重建并发。项目使用 advisory lock 保护工作区更新，但运维仍应避免无意义重复任务。