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.txt

2. 配置环境变量

cp .env.example .env
# 编辑 .env，填入你的 HuggingFace Token

3. 构建索引

将 PDF 文件放入 ./pdfs/ 目录，然后运行：

python build_index.py
# 或指定自定义 PDF 目录：
python build_index.py /path/to/your/pdfs

4. 配置 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	列出所有可用文档编号	无

自定义

核心只需改两处：

1. build_index.py — 修改 PDF_DIR 路径或通过命令行参数指定；如果文档不是 PDF 格式，替换 extract_text_from_pdf 函数
2. server.py — 修改 instructions 中的助手描述和工具描述

其余组件（文本切片、向量化、ChromaDB、MCP 协议）均可直接复用。

限制

• 仅限本地使用，需在运行 Claude Desktop 的机器上启动 MCP Server
• bge-m3 模型约 2.2GB，首次加载需数秒
• 如需远程访问，需将服务部署到云端或使用 Claude Projects 上传文档