R2R 检索系统的 MCP 服务器接入指南让 Claude Desktop 直连向量检索、知识图谱与 RAG【免费下载链接】R2RSoTA production-ready AI retrieval system. Agentic Retrieval-Augmented Generation (RAG) with a RESTful API.项目地址: https://gitcode.com/GitHub_Trending/r2/R2RR2RRetrieval-Augmented Generation项目将自身定位为基于 Model Context ProtocolMCP的检索服务器为 Claude 等 AI 客户端提供知识库检索能力。本文以 docs/cookbooks/mcp.md 为主线结合 py/r2r/mcp.py 源码与 Python SDK 实现完整讲解 MCP 服务器的安装、Claude Desktop 配置、search / rag 两个核心工具的用法、返回结果格式以及底层调用链帮助你在一小时内把本地或云端 R2R 服务接入 Claude用自然语言完成向量搜索、图谱搜索、Web 搜索与文档搜索。MCP 是什么R2R 如何扮演 MCP 服务器Model Context ProtocolMCP是 AI 客户端如 Claude Desktop与外部工具/数据源之间的标准化通信协议。一个 MCP 服务器对外暴露一组可被大模型调用的工具tool客户端负责把这些工具的能力交给模型决策。R2R 的 MCP 服务器封装在 py/r2r/mcp.py 中。该文件基于官方mcpPython 包提供的FastMCP构建启动后即注册一个名为R2R Retrieval System的 MCP 服务器# 来自 py/r2r/mcp.py try: from mcp.server.fastmcp import FastMCP mcp FastMCP(R2R Retrieval System) except Exception as e: raise ImportError( MCP is not installed. Please run pip install mcp ) from e # Pass lifespan to server mcp FastMCP(R2R Retrieval System)从源码结构可以看到服务器注册了search与rag两个异步工具它们内部通过 R2R 官方 Python SDK 的R2RClient调用 REST API。因此MCP 服务器本身不持有数据它是Claude ↔ R2R API之间的适配层Claude 说帮我检索MCP 工具负责把检索请求转发给 R2R 服务并格式化返回。核心能力一览MCP 服务器为 Claude 提供以下五类检索能力对应 docs/cookbooks/mcp.md 的 Features 章节Vector Search向量搜索基于语义相似度查找最相关的文本分块chunk。Graph Search图谱搜索在知识图谱中探索实体、关系与社区之间的关联。Web SearchWeb 搜索从在线来源检索信息。Document Search文档搜索访问并查询本地上下文的文档。RAG检索增强生成基于检索到的上下文生成答案。这些能力并非 MCP 层凭空实现而是对应 R2R v3 API 中AggregateSearchResult的多个检索通道。在 py/shared/abstractions/search.py 中可以看到聚合结果的数据结构它同时承载五类结果class AggregateSearchResult(R2RSerializable): chunk_search_results: Optional[list[ChunkSearchResult]] None graph_search_results: Optional[list[GraphSearchResult]] None web_page_search_results: Optional[list[WebPageSearchResult]] None web_search_results: Optional[list[WebSearchResult]] None document_search_results: Optional[list[DocumentResponse]] None环境准备Prerequisites接入前需要准备以下环境依赖说明Claude DesktopmacOS 或 Windows作为 MCP 客户端承载工具调用Node.jsClaude Desktop 配置 MCP 服务器时的运行时依赖Python 3.6 及以上运行 MCP 服务器脚本实际使用时建议以 py/pyproject.toml 声明的版本为准mcpPython 包提供FastMCP与mcp命令行工具通过pip install mcp安装可用的 R2R API 服务本地启动的 R2R 服务默认http://localhost:7272或云端部署实例安装方式本地安装与云端安装本地安装在本地机器上执行两条命令先安装mcp包再通过mcp install命令把 R2R 的 MCP 服务器注册到客户端pip install mcp mcp install r2r/mcp.py -v R2R_API_URLhttp://localhost:7272-v用于向服务器进程注入环境变量-v KEYVALUE格式。R2R_API_URL指定 R2R API 的地址。默认端口7272与 SDK 的默认值一致见下文底层调用链。执行前请确认本地 R2R API 服务已在指定 URL 上启动否则后续检索会失败。命令中的r2r/mcp.py对应仓库 py/r2r/mcp.py请替换为克隆到本机后的实际绝对路径如/my/path/to/R2R/py/r2r/mcp.py。云端安装使用云端部署的 R2R 服务时把 URL 换成 API Key 即可pip install mcp mcp install r2r/mcp.py -v R2R_API_KEYyour_api_key_hereAPI Key 的传递方式与 SDK 完全一致在 py/sdk/base/base_client.py 中R2RClient会读取环境变量R2R_API_KEY作为请求凭据并通过x-api-key请求头发送给服务端见 py/sdk/base/base_client.py。因此 MCP 服务器进程只要继承了该环境变量SDK 就能自动带上鉴权头。手动添加到 Claude Desktop备用方案文档明确说明只有当pip install方式失败时才需要手动配置大多数情况下上面的安装命令已足够让 R2R 服务器被 Claude 识别。如果确实需要手动配置打开 Claude Desktop进入 SettingsmacOS点击 Claude 菜单 → Settings...Windows点击 Claude 菜单 → Settings...在 Settings 左侧栏点击 Developer然后点击 Edit Config。在配置文件中加入 R2R 服务器条目{ mcpServers: { r2r: { command: mcp, args: [run, /my/path/to/R2R/py/r2r/mcp.py] } } }保存配置文件并重启 Claude Desktop。重启后输入框右下角会出现锤子hammer图标表示 MCP 工具已就绪。手动配置的本质与mcp install相同通过mcp run启动 py/r2r/mcp.py 脚本。若采用此方式R2R 服务地址/API Key 需要额外通过环境变量注入到该进程与-v参数等价。py/r2r/mcp.py 的入口逻辑也支持直接执行python r2r/mcp.py会调用mcp.run()启动服务器便于先本地验证再接入客户端。两个核心工具search 与 ragMCP 服务器对外提供两个主要工具见 py/r2r/mcp.py。search执行多源检索并返回格式化结果mcp.tool() async def search(query: str) - str: Performs a ... client R2RClient() search_response client.retrieval.search(queryquery) return format_search_results_for_llm(search_response.results)作用跨向量、图谱、Web、文档四类来源执行检索返回带Source ID的结构化文本。入参仅一个query字符串。返回值search_response.results是AggregateSearchResult经format_search_results_for_llm格式化为适合大模型阅读的纯文本。rag检索增强生成mcp.tool() async def rag(query: str) - str: Perform a Retrieval-Augmented Generation query client R2RClient() rag_response client.retrieval.rag(queryquery) return rag_response.results.generated_answer作用先检索相关上下文再基于上下文生成连贯答案。返回值直接返回RAGResponse.generated_answer即最终生成的回答文本见 py/shared/api/models/retrieval/responses.py 中的generated_answer字段定义。在 Claude 中使用配置完成后Claude 会在适当时机自动调用这两个工具你也可以用自然语言显式触发搜索让 Claude 用特定查询检索知识库。例如Search for information about vector databases in our documentation。RAG请求 Claude 基于检索上下文生成答案。例如Use RAG to answer: What are the best practices for knowledge graph integration?。结果格式化返回给大模型的结构化文本format_search_results_for_llmpy/r2r/mcp.py是 MCP 服务器中最重要的展示层逻辑。它把AggregateSearchResult按四类来源逐段输出并且使用id_to_shorthand把完整 UUID 压缩为前 7 位短 IDdef id_to_shorthand(id: str) - str: return str(id)[:7]各来源的格式化规则如下向量搜索结果输出Vector Search Results:标题每个 chunk 输出Source ID [前7位ID]与text正文。图谱搜索结果输出Graph Search Results:并根据content的类型分支处理社区community输出Community Name、ID、Summary实体entity输出Entity Name、Description关系relationship输出Relationship: subject-predicate-object。Web 搜索结果输出Web Search Results:逐条输出Title、Link、Snippet。本地上下文文档输出Local Context Documents:包含Full Document ID、Shortened Document ID、Document Title、Summary若文档含分块还会继续输出每个Chunk ID及其text。示例输出调用 search 工具后Claude 收到的典型结果如下来自 docs/cookbooks/mcp.md 的 Example Outputs 章节Vector Search Results: Source ID [abc1234]: Text content from the vector search... Graph Search Results: Source ID [def5678]: Entity Name: Sample Entity Description: This is a description of the entity... Web Search Results: Source ID [ghi9012]: Title: Sample Web Page Link: https://example.com Snippet: A snippet from the web page... Local Context Documents: Full Document ID: jkl3456... Shortened Document ID: jkl3456 Document Title: Sample Document Summary: A summary of the document... Chunk ID abc1234: Text content from the document chunk...短 ID 的设计非常实用它既保留了可追溯性abc1234可还原为完整 UUID又大幅压缩了送入大模型上下文的 token 量避免长 UUID 挤占上下文窗口。底层调用链MCP 工具如何驱动 R2R API理解调用链有助于排查问题也能帮你用同样的模式扩展新工具。整个链路如下Claude Desktop └─ mcp run py/r2r/mcp.pyFastMCP 服务器注册 search / rag 工具 └─ R2RClientpy/sdk/sync_client.py └─ RetrievalSDK.search() / .rag()py/sdk/sync_methods/retrieval.py └─ POST {base_url}/v3/retrieval/search 或 /v3/retrieval/rag └─ R2R API 服务默认 http://localhost:7272关键实现细节SDK 客户端py/sdk/sync_client.py 中的R2RClient聚合了RetrievalSDK等子客户端MCP 工具直接用client.retrieval.search()与client.retrieval.rag()。端点RetrievalSDK.search向v3/retrieval/search发送 POSTrag向v3/retrieval/rag发送 POST见 py/sdk/sync_methods/retrieval.py 与 py/sdk/sync_methods/retrieval.py。服务地址与鉴权R2RClient的默认地址来自环境变量R2R_API_BASE缺省为http://localhost:7272py/sdk/base/base_client.pyR2R_API_KEY环境变量提供x-api-key鉴权。这就是mcp install ... -v注入变量的底层依据——文档中的R2R_API_URL与 SDK 的R2R_API_BASE本质都指向同一个 R2R API 地址配置时请确保两者与实际服务端口一致。RAG 响应的取数rag工具直接读取rag_response.results.generated_answer而RAGResponse中还包含search_resultsAggregateSearchResult与citations结构化引用信息py/shared/api/models/retrieval/responses.py。当前 MCP 工具只返回最终答案如需把引用来源一并暴露给 Claude可以在此基础上扩展。排查指南Troubleshooting根据 docs/cookbooks/mcp.md 的 Troubleshooting 章节常见问题与对策如下服务器没有出现在 Claude 中检查 Claude Desktop 配置文件claude_desktop_config.json的 JSON 格式是否正确mcpServers条目是否完整。本地安装检索失败确认 R2R API 服务确实在指定的 URL 上运行。默认地址是http://localhost:7272可用curl http://localhost:7272/v3/system/health类请求自测具体健康检查端点以 py/core/main/api/v3/system_router.py 为准。云端安装鉴权失败验证 API Key 是否有效并确认-v R2R_API_KEY...已正确注入到 MCP 服务器进程的环境变量。仍有异常查看 Claude Desktop 的日志输出定位是 MCP 连接问题还是 R2R API 返回的 4xx/5xx 错误。进一步扩展探索更多 MCP 服务器将 R2R 与其它 MCP 服务器组合让 Claude 获得更丰富的工具集。自定义工具py/r2r/mcp.py 中每个工具只是mcp.tool()装饰的一个异步函数。你可以照此模式新增工具例如暴露client.retrieval.agent()对话式 Agent、client.documents的文档管理能力或让rag工具额外返回citations结构化引用——所有能力都已在 py/sdk/sync_methods 中封装好无需直接拼接 HTTP 请求。参与社区共建分享你的接入经验与使用案例。需要特别说明的是R2R 的 MCP 服务器是一个薄适配层它把 R2R 完整的检索体系向量、图谱、Web、文档、RAG以标准化的工具形式交付给 Claude。要真正发挥它的价值还需先通过 R2R 的 ingestion 流程把文档灌入知识库、配置好 embedding 与 LLM参考 py/core/configs/full.toml并保证 R2R API 服务可用——MCP 接入本身只是打通最后一公里。【免费下载链接】R2RSoTA production-ready AI retrieval system. Agentic Retrieval-Augmented Generation (RAG) with a RESTful API.项目地址: https://gitcode.com/GitHub_Trending/r2/R2R创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考