mcp-rag

让 Claude Desktop / Cursor 等 AI 助手智能检索你的本地文档的 MCP Server。

一条命令启动，AI 通过 MCP 协议 即可搜索你的知识库。

为什么选 mcp-rag？

市面上的 MCP RAG 方案（mcp-local-rag、RAG-MCP 等）大多是单路检索 + 无精排，中文支持差，效果有限。

mcp-rag 做了完整的检索工程优化：

能力	mcp-rag	同类项目
混合检索（BM25 + 向量 + RRF 融合）	✅	大多单路
Cross-Encoder 精排	✅	❌
Contextual Retrieval（Anthropic 方案）	✅	❌
中英文原生支持（BGE 系列）	✅	仅英文或部分
内置评测命令	✅	❌
Harness 层（审计日志 + 可观测性）	✅	❌
文件监听 + 增量索引	✅	❌

环境要求

• Python >= 3.13
• 约 3GB 磁盘空间（首次运行自动下载 Embedding + Rerank 模型）
• [可选] Ollama（开启 Contextual Retrieval 时需要，用于生成上下文摘要）

安装

pip install mcp-rag

或从源码安装：

git clone https://github.com/your-username/mcp-rag.git
cd mcp-rag
pip install .

快速开始

1. 准备文档目录

把你的文档（.md、.txt）放到一个目录下，例如 ~/my_docs/。

2. 启动 Server

mcp-rag serve --docs-dir ~/my_docs

首次启动会自动下载模型（约 1.2GB Embedding + 1.1GB Rerank），之后启动无需重复下载。

3. 连接 AI 客户端

Claude Desktop — 编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "mcp-rag": {
      "command": "mcp-rag",
      "args": ["serve", "--docs-dir", "/path/to/your/docs"]
    }
  }
}

Cursor — 在 Settings > MCP 中添加相同配置。

连接成功后，直接对 AI 说"帮我搜索 xxx"即可。

4. 可用工具

工具	说明
search	混合检索，返回最相关的文档片段
list_sources	列出已索引的文档
index_status	查看索引状态和搜索统计

配置

支持三层配置，优先级：命令行 > 配置文件 > 默认值。

创建 mcp-rag.toml（放在项目目录或 ~/.mcp-rag.toml）：

[server]
docs_dir = "./my_docs"

[search]
top_k = 5
use_rerank = true        # Cross-Encoder 精排（默认开启）
use_contextual = false   # Contextual Retrieval（需要 Ollama）

常用命令行参数：

mcp-rag serve --docs-dir ./docs          # 指定文档目录
mcp-rag serve --no-rerank                # 关闭精排（更快）
mcp-rag serve --contextual               # 开启 Contextual Retrieval
mcp-rag eval                             # 运行检索质量评测
mcp-rag eval --compare                   # 对比 Rerank ON/OFF 效果

检索流程

查询 → BM25 关键词检索 ──┐
                         ├→ RRF 融合排序 → Cross-Encoder 精排 → 返回 top-k
查询 → 向量语义检索 ──────┘

• BM25：精确匹配关键词、错误码、专有名词
• 向量检索：语义理解，"汽车" 能匹配 "轿车"
• RRF 融合：按排名合并两路结果
• Cross-Encoder Rerank：query 和候选片段拼接输入 BERT，深度交叉打分

License

MIT