Local Knowledge MCP — PDF RAG + MCP Server
将本地 PDF 文档构建为向量知识库，通过 MCP 协议接入 Claude Desktop 实现语义检索对话。
项目结构
local-knowledge-mcp/
├── build_index.py # 索引构建脚本（一次性运行）
├── server.py # MCP Server（Claude Desktop 调用）
├── requirements.txt # Python 依赖
├── .env.example # 环境变量示例
└── README.md运行后会生成：
chroma_db/— 向量数据库（已在 .gitignore 中排除）
技术栈
| 组件 | 库 | 职责 |
|---|---|---|
| PDF 解析 | PyMuPDF (fitz) | PDF → 纯文本 |
| 文本切片 | 手写 chunk_text() | 长文本 → 500字小块，80字重叠 |
| 向量化 | sentence-transformers + BAAI/bge-m3 | 文本 → 1024维向量 |
| 向量数据库 | ChromaDB | 向量存储 + 语义检索 |
| API 服务 | mcp (FastMCP) | 暴露工具给 Claude Desktop |
数据流
PDF 文件
│ PyMuPDF
▼
纯文本
│ chunk_text() — 500字/块，80字重叠
▼
文本块
│ BAAI/bge-m3 模型
▼
向量 (1024维)
│ ChromaDB
▼
向量数据库 (本地持久化)
│ MCP Server (stdio)
▼
Claude Desktop 调用快速开始
1. 安装依赖
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt2. 配置环境变量
cp .env.example .env
# 编辑 .env，填入你的 HuggingFace Token3. 构建索引
将 PDF 文件放入 ./pdfs/ 目录，然后运行：
python build_index.py
# 或指定自定义 PDF 目录：
python build_index.py /path/to/your/pdfs4. 配置 Claude Desktop
编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：
{
"mcpServers": {
"local-knowledge": {
"command": "/path/to/your/venv/bin/python",
"args": ["/path/to/your/server.py"],
"env": {
"HF_TOKEN": "your_huggingface_token_here"
}
}
}
}修改配置后需完全退出 Claude (Cmd+Q) 再重新打开。
MCP Server 提供的工具
| 工具名 | 功能 | 参数 |
|---|---|---|
search | 语义搜索文档内容 | query (关键词/问题), n_results (默认8) |
search_by_article | 按编号查看特定文档 | article_num (编号), keyword (可选过滤) |
list_articles | 列出所有可用文档编号 | 无 |
自定义
核心只需改两处：
build_index.py— 修改PDF_DIR路径或通过命令行参数指定；如果文档不是 PDF 格式，替换extract_text_from_pdf函数server.py— 修改instructions中的助手描述和工具描述
其余组件（文本切片、向量化、ChromaDB、MCP 协议）均可直接复用。
限制
- 仅限本地使用，需在运行 Claude Desktop 的机器上启动 MCP Server
- bge-m3 模型约 2.2GB，首次加载需数秒
- 如需远程访问，需将服务部署到云端或使用 Claude Projects 上传文档