在 LlamaIndex 中使用 LlamaCloud MCP Servers Tools将 LlamaCloud Indexes 与 LlamaExtract 接入任意 MCP 宿主【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_indexLlamaCloud 是 LlamaIndex 的托管文档处理平台而 LlamaCloud MCP Servers 是 LlamaIndex 官方提供的 MCPModel Context Protocol服务器它把 LlamaCloud Indexes云端索引与 LlamaExtract结构化信息抽取 Agent封装为标准 MCP 工具可被 Claude Desktop、claude-code、IDE 以及 LlamaIndex 自身的工作流直接消费。读完本文你将掌握llamacloud-mcp的安装方式、Claude 配置写法、命令行参数与三种传输方式stdio / streamable-http / sse并能结合仓库源码理解其底层与 LlamaIndex 工具体系的对接原理。LlamaCloud MCP 的背景为什么需要它在进入具体配置之前先回顾 MCP 在整个体系中的位置。LlamaIndex 官方文档把 MCP 描述为“AI 应用的 USB-C 接口”——一个开放标准协议让大语言模型通过结构化 API 调用与外部工具、数据源交互见 MCP 模块导览。MCP 采用客户端-服务器架构MCP HostsClaude Desktop、IDE、AI 工具等希望经由 MCP 访问数据的应用MCP Clients与 MCP 服务器保持 1:1 连接的协议客户端MCP Servers通过标准化协议暴露能力工具、资源、提示词的轻量服务。LlamaCloud MCP 服务器正是「服务器」这一层它把 LlamaCloud 的服务能力索引检索、抽取 Agent翻译成 MCP 协议供任意宿主调用。LlamaIndex 提供了官方 MCP 服务器来集成 LlamaCloud Indexes 与 LlamaExtract与此同时llamacloud-mcpPython 包提供了另一种实现同时支持查询query与抽取extraction两类能力——以 LlamaCloud Indexes 作为知识库、以 LlamaExtract Agent 完成结构化抽取。本文聚焦该包的安装与使用。安装 llamacloud-mcpllamacloud-mcp是独立的 Python 包可通过pip或uvx两种方式获取pip install llamacloud-mcp # 或 uvx llamacloud-mcplatestpip install适用于已经运行 Python 环境的场景将包安装到当前环境中uvx llamacloud-mcplatestuvx是 uv 提供的工具运行器无需预先安装包直接拉取最新版本运行适合在配置文件中以命令行方式启动服务器下文 Claude 配置即采用此方式。两种方式最终都会提供llamacloud-mcp命令行入口可通过--help查看全部可用参数。在 Claude 等 MCP 宿主中使用MCP 服务器本身不独立提供界面它需要挂载到某个宿主应用中。以 claude-code 等支持 MCP 的宿主为例需要在其配置文件中注册服务器。官方给出的配置示例如下{ mcpServers: { llama_index_docs_server: { command: uvx, args: [ llamacloud-mcplatest, --index, your-index-name:Description of your index, --index, your-other-index-name:Description of your other index, --extract-agent, extract-agent-name:Description of your extract agent, --project-name, Your LlamaCloud Project Name, --org-id, Your LlamaCloud Org ID, --api-key, Your LlamaCloud API Key ] }, filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, your directory you want filesystem tool to have access to ] } } }这份配置的核心要点mcpServers对象每个键是一个服务器实例名本例注册了两个服务器——llama_index_docs_serverLlamaCloud与filesystem官方文件系统服务器用于对比演示 MCP 生态的多样性command/args定义如何启动服务器。uvx启动llamacloud-mcplatest随后的args数组是该服务器的全部命令行参数可重复参数--index可以出现多次每次携带一个索引的「名称:描述」--extract-agent同理可注册多个抽取 Agent。名称后的冒号描述会被 MCP 协议暴露给模型帮助 LLM 判断何时调用哪个工具因此描述应写清楚该索引/Agent 的用途认证三件套--project-name项目名、--org-id组织 ID、--api-keyAPI 密钥均可在 LlamaCloud 控制台获取。配置完成后重启宿主应用LlamaCloud 的检索与抽取能力即以工具形式出现在模型可调用的列表中。命令行通用用法与参数详解除了通过宿主配置文件挂载llamacloud-mcp也支持直接从命令行启动服务器便于调试与自定义传输方式llamacloud-mcp --index index-name:Description --extract-agent name:description --org-id YOUR_ORG_ID --project-id YOUR_PROJECT_ID --api-key YOUR_API_KEY --transport streamable-http常用参数汇总参数说明--index 名称:描述注册一个 LlamaCloud Index 作为知识库可重复传入多个--extract-agent 名称:描述注册一个 LlamaExtract Agent 用于结构化抽取可重复传入多个--org-idLlamaCloud 组织 ID用于租户隔离与鉴权--project-idLlamaCloud 项目 ID注意与 Claude 配置中的--project-name相区分两者分别对应项目的 ID 与名称--project-nameLlamaCloud 项目名称--api-keyLlamaCloud API 密钥--transport传输协议可选stdio默认、streamable-http、sse需要说明的是--index与--extract-agent参数中的描述文本会被 MCP 服务器转发为工具的 description 字段直接影响 LLM 的工具选择准确性建议使用「该数据源包含什么内容、适合回答哪类问题」式的描述。传输方式stdio、streamable-http 与 sse默认情况下MCP 服务器以stdio传输方式启动——服务器与宿主通过标准输入/输出通信适合 Claude Desktop 这类原生支持 MCP 的桌面宿主。但并非所有宿主都支持 stdio。文档明确指出服务器同样支持streamable-http或sse两种基于 HTTP 的传输方式适用于通过 HTTP 与 MCP 服务器通信的宿主。两种方式的区别SSEServer-Sent EventsMCP 早期的 HTTP 传输方案客户端与服务端之间通过单向 SSE 流推送事件Streamable HTTP更新的 MCP 传输规范支持请求-响应与流式两种模式被 MCP 官方视为推荐方案。从本仓库的 MCP 客户端源码可以佐证这一传输矩阵在 client.py 中BasicMCPClient的_run_session方法会根据 URL scheme 自动选择传输方式——http/https时判断是否为 SSE 端点enable_sse通过transportsse查询参数或路径中的/sse识别否则走streamable_http_client其余情况走stdio_client。也就是说服务端支持三种传输客户端也具备对应的自动协商能力。实际部署时本地桌面宿主用默认的 stdio 即可需要跨进程、跨网络暴露服务时使用--transport streamable-http或sse并对外提供 HTTP 端点。将 LlamaCloud MCP 工具接入 LlamaIndex 工作流LlamaCloud MCP 服务器不仅服务外部宿主也能反过来增强 LlamaIndex 自身的 Agent 工作流。结合 llamaindex_mcp 指南消费方式非常直接——把运行中的 MCP 服务器例如以streamable-http启动的 LlamaCloud MCP转换为 LlamaIndex 的 FunctionTool 列表from llama_index.tools.mcp import BasicMCPClient, McpToolSpec # 连接到以 streamable-http 运行的 LlamaCloud MCP 服务器 mcp_client BasicMCPClient(http://127.0.0.1:8000/mcp) mcp_tool_spec McpToolSpec(clientmcp_client) # 获取工具列表异步接口避免阻塞事件循环 tools await mcp_tool_spec.to_tool_list_async()拿到tools后即可注入任意 Agent例如FunctionAgentfrom llama_index.core.agent.workflow import FunctionAgent from llama_index.llms.openai import OpenAI agent FunctionAgent( toolstools, llmOpenAI(modelgpt-5-mini), system_promptYou are a helpful assistant., ) response await agent.run(Your query here)BasicMCPClient对连接方式的抽象也覆盖了多种形态见 llamaindex_mcp.md# Server-Sent Events sse_client BasicMCPClient(https://example.com/sse) # Streamable HTTP http_client BasicMCPClient(https://example.com/mcp) # 本地进程stdio local_client BasicMCPClient(python, args[server.py])这意味着 LlamaCloud MCP 服务器无论以哪种传输方式暴露都能被统一包装成 LlamaIndex 工具。源码级原理客户端如何把 MCP 工具变为 FunctionTool理解McpToolSpec的内部机制有助于排查工具参数不匹配等问题。其实现位于 base.py关键流程如下fetch_tools调用client.list_tools()拉取服务器端工具列表若设置了allowed_tools则仅保留指定名称的工具传入空列表会返回空列表并给出警告日志动态 Schema 生成create_model_from_json_schema依据 MCP 工具声明的 JSON Schema含$defs递归类型定义动态构建 Pydantic 模型作为ToolMetadata.fn_schema参数预填global_partial_params可对所有工具注入公共参数如统一的项目 IDpartial_params_by_tool可对单个工具覆盖或移除值为None时删除该参数——预填的参数会从模型 Schema 中移除避免重复要求 LLM 提供工具包装_create_tool_fn生成的async_tool_fn(**kwargs)内部转发为client.call_tool(tool_name, kwargs)再包成FunctionTool资源支持include_resourcesTrue时还会把 MCP 资源静态资源与资源模板一并转换为工具。此外client.py中的BasicMCPClient继承自 MCP 官方ClientSession提供了list_tools、call_tool、list_resources、read_resource、list_prompts、get_prompt等完整能力对于需要 OAuth 鉴权的服务器还提供with_oauth工厂方法默认使用内存 Token 存储重启后 Token 会丢失生产环境应自行实现TokenStorage。服务端启动参数中的--org-id、--api-key正是在客户端连接后由 MCP 工具调用携带到 LlamaCloud 侧完成鉴权的。进阶把 LlamaCloud MCP 与其他 LlamaIndex 工作流组合MCP 在 LlamaIndex 中的三种典型用法见 MCP 模块导览中本主题覆盖的是第三种——「在 LlamaIndex 工作流中使用 LlamaCloud 服务」。与前两种用法互补消费外部 MCP 服务器用llama-index-tools-mcp把任意第三方 MCP 工具接入 LlamaIndex前文已演示把自有工作流发布为 MCP使用workflow_as_mcp将自定义 LlamaIndex Workflow 转换为 FastMCP 服务器详见 convert_existing 指南。典型组合是先以llamacloud-mcp --transport streamable-http启动 LlamaCloud 查询/抽取服务再在 LlamaIndex 侧通过BasicMCPClient McpToolSpec将检索能力注入 Agent同时用workflow_as_mcp将 Agent 自身的工作流对外暴露——形成「LlamaCloud 数据源 → MCP → LlamaIndex Agent → MCP → 下游宿主」的完整闭环。小结LlamaCloud MCP Servers 让 LlamaIndex 的托管能力LlamaCloud Indexes 检索、LlamaExtract 结构化抽取通过标准 MCP 协议开放给整个 AI 生态。本文覆盖了其核心使用路径pip/uvx安装、Claude 配置文件注册、命令行参数--index、--extract-agent、--org-id、--project-id、--api-key、--transport、三种传输方式的选择以及如何借助BasicMCPClient/McpToolSpec将这些工具无缝接入 LlamaIndex Agent。相关源码可继续深入阅读 client.py 与 base.py官方配置示例见 llamacloud_mcp.md。【免费下载链接】llama_indexLlamaIndex is the document processing platform for AI项目地址: https://gitcode.com/GitHub_Trending/ll/llama_index创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
