/ 目录 / 演练场 / mcp-use
← 全部服务器 ↗ GitHub
● 社区 mcp-use ⚡ 即开即用

mcp-use

作者 mcp-use · mcp-use/mcp-use

Python 库，可将多个 MCP 服务器接入一个 LangChain agent，或者不通过 LLM 直接运行它们。

mcp-use 是一个客户端 Python 框架。指向 N 个 MCP 服务器配置（stdio 或 HTTP），用任何兼容 LangChain 的 LLM 将它们包装在 MCPAgent 中，你就得到了一个可工作的多服务器 agent。还支持不经过 LLM 的直接 MCPClient 工具调用——对脚本化自动化很有用。

▶ 观看演示 📦 安装 💡 使用场景

为什么要用

核心特性

实时演示

实际使用效果

mcp-use.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "mcp-use": {
      "command": "uvx",
      "args": [
        "mcp-use"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "mcp-use": {
      "command": "uvx",
      "args": [
        "mcp-use"
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "mcp-use": {
      "command": "uvx",
      "args": [
        "mcp-use"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标，然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "mcp-use": {
      "command": "uvx",
      "args": [
        "mcp-use"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "mcp-use",
      "command": "uvx",
      "args": [
        "mcp-use"
      ]
    }
  ]
}

Continue 使用服务器对象数组，而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "mcp-use": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-use"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add mcp-use -- uvx mcp-use

一行命令搞定。用 claude mcp list 验证，claude mcp remove 卸载。

使用场景

实战用法： mcp-use

构建一个使用 playwright + 文件系统 + postgres 的自定义 agent

👤 构建垂直 agent 的 Python 开发者 ⏱ ~45 min intermediate

何时使用： 你需要一个可重复的自动化流程（不是 Claude Desktop），链接浏览器 + 文件 + 数据库。

前置条件
  • Python 3.10+、uv 或 pip — 标准安装
  • 一个 LLM API 密钥（OpenAI / Anthropic） — 将其设置为 LangChain 模型期望的环境变量
步骤
  1. 定义服务器配置
    编写一个 mcp-use 配置，连接到 playwright（通过 npx 的 stdio）、postgres（通过 uvx 的 stdio）和文件系统（本地路径作用域）。✓ 已复制
    → 匹配架构的 JSON/dict 配置
  2. 接线 agent
    使用 ChatAnthropic（claude-sonnet-4）和上面的配置创建一个 MCPAgent。最大迭代次数 = 15。✓ 已复制
    → Agent 实例已准备好 .run()
  3. 运行任务
    运行：'爬取 docs.example.com，将每个页面保存到 ./knowledge/，然后将标题索引到 postgres docs 表。'在日志中观察工具调用。✓ 已复制
    → 任务完成，数据落地到预期位置

结果： 一个可脚本化的 agent，你可以计划、部署或嵌入它——不受桌面客户端的限制。

注意事项
  • Agent 在服务器之间循环，消耗令牌 — 设置严格的 max_iterations，使用一个能很好遵循指令的 LLM——GPT-4o-mini 常在复杂链上循环，使用更强的模型
  • stdio 服务器在崩溃后变成僵尸进程 — 始终使用 async 上下文管理器模式——它处理清理；不要自己管理进程
搭配使用： fastmcp · mcp-agent

从 Python 调用 MCP 工具而不需要 LLM

👤 自动化运维任务的工程师 ⏱ ~20 min intermediate

何时使用： 你想在一个更大的 Python 管道中确定性地调用 MCP 工具。

步骤
  1. 直接连接客户端
    使用 MCPClient 连接到我的文件系统 MCP。列出可用的工具。✓ 已复制
    → 工具名称 + 架构已打印
  2. 调用带类型参数的工具
    调用 write_file，path='./out.txt'，content='hello'。确认返回值。✓ 已复制
    → 文件已写入，不涉及 LLM
  3. 链接到你的业务逻辑
    将其包装在一个调用 MCP 工具的函数 save_report(df) 中——集成到我现有的 Python ETL。✓ 已复制
    → 可重用的函数

结果： MCP 即库：Claude Desktop 使用的相同服务器也可从普通 Python 调用。

注意事项
  • 错误不会自然冒泡——MCP 错误以 isError: true 的结果对象形式出现 — 在每次调用后检查 result.isError；不要假设成功

构建一个为每个请求选择正确 MCP 的路由 agent

👤 发布 agent 产品的团队 ⏱ ~60 min advanced

何时使用： 用户发送混合请求（代码、数据、网络）——一个包含 50 个工具的单体提示会降级；你想要路由。

步骤
  1. 定义服务器组
    将我的 MCP 服务器分成 3 组：'code'（git、github）、'data'（postgres、bigquery）、'web'（firecrawl、playwright）。✓ 已复制
    → 3 个独立的 agent 配置
  2. 添加路由层
    编写一个分类器提示，基于用户的意图选择一个组。使用它按需实例化匹配的 MCPAgent。✓ 已复制
    → 分类器返回 {code, data, web} 之一
  3. 用混合流量测试
    通过路由器运行 10 个不同的请求。记录哪个组处理了每个请求以及答案是否正确。✓ 已复制
    → 准确度表 + 延迟统计

结果： 一个模块化的 agent 系统，每个请求只看到与其相关的工具——更好的准确度，更低的令牌成本。

注意事项
  • 请求需要两个组的边界情况（例如，'爬取 + 保存到数据库'） — 定义第四个 'cross' 组或通过 mcp-agent 回退到 Orchestrator 模式
搭配使用： mcp-agent

组合

与其他 MCP 搭配，撬动十倍杠杆

mcp-use + mcp-agent

使用 mcp-use 连接服务器，mcp-agent 用于工作流模式（orchestrator/evaluator）

构建一个 evaluator-optimizer 循环，其中一个 writer agent 使用 mcp-use 访问文件系统 + git，一个 critic agent 使用相同的服务器审查输出。✓ 已复制
mcp-use + fastmcp

用 FastMCP 编写一个服务器，然后用 mcp-use 脚本与之交互——端到端的 Python agent 堆栈

服务器：通过 FastMCP 暴露我们的定价 API。客户端：在定价模拟脚本中使用 mcp-use 调用它。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
MCPClient(config) 服务器配置 dict/path 任何 mcp-use 脚本的入口点 free
MCPAgent(llm, client, max_steps) LangChain 聊天模型 + MCPClient 当你想要 LLM 驱动的工具选择时 LLM calls only
client.list_tools() server_name? 在调用前内省可用的内容 free
client.call_tool(name, args) tool_name, dict 直接确定性调用——不涉及 LLM depends on tool
MCPServer decorator API @server.tool() on functions 不太常见；FastMCP 通常更清洁用于服务器构建 free

成本与限制

运行它的成本

API 配额
mcp-use 本身没有；取决于 LLM 和下游 MCP
每次调用 Token 数
LLM 驱动的调用消耗令牌——通常的 LangChain agent 成本模型
费用
库是免费的，LLM 使用不是
提示
对于确定性流程，直接使用 client.call_tool——跳过 LLM。将 MCPAgent 保留用于真正模棱两可的任务。

安全

权限、密钥、影响范围

凭据存储： 根据基础 MCP——mcp-use 不添加一层
数据出站： LLM 提供商 + 每个连接的 MCP

故障排查

常见错误与修复

启动 stdio 服务器时的 ConnectionError

你的配置中的 command 不在 PATH 上或包未安装。手动测试：首先在终端中运行相同的 npx -y ...。

验证： which npx && npx -y @modelcontextprotocol/server-filesystem --help
Agent 正确调用工具但答案错误

通常是 LLM 问题——尝试更强的模型。GPT-4o-mini 和开源 7B 模型经常误解工具结果。

Event loop 已在运行错误

你在 async 上下文中调用 sync API。在整个过程中使用 await 和 async 客户端方法。

来自服务器 A 的工具遮蔽了服务器 B 中的名称

在你的配置中为每个服务器的工具名称添加前缀，或依赖库的内置命名空间处理（设置 namespace=True）。

替代方案

mcp-use 对比其他方案

替代方案何时用它替代权衡
mcp-agent你想要工作流模式（orchestrator、router、evaluator）内置其中更有主见；如果你想要原始的 LangChain，灵活性更低
Official Python MCP SDK你想要最低级的客户端——没有 LangChain，没有抽象更多的管道代码
LangGraph + MCP你需要带检查点的有状态多轮图更陡峭的学习曲线；对于简单的 agent 来说过度设计

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills