mcp-agent
基于 MCP 协议构建 AI Agent 的 Python 框架, 提供 6 种可组合工作流模式
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
基于 MCP 协议构建 AI Agent 的 Python 框架, 提供 6 种可组合工作流模式
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
想象一下, 你是一家电商公司的后端工程师, 接到一个任务: 让 AI 能帮用户查询订单、推荐商品、处理退货。但 AI 不能直接操作数据库, 只能通过「工具」和这个世界打交道。MCP (Model Context Protocol) 就是为此而生的协议: 它让 AI 能够标准化地调用外部工具。而 mcp-agent 正是站在这个协议肩膀上的开发框架, 帮助你把这些工具组装成真正能用的 AI Agent。
过去两年, AI Agent 领域经历了从「LLM + Prompt」到「LLM + Tool Use」再到「多 Agent 协作」的演进。Anthropic 在 2025 年初发布的《Building Effective Agents》总结了几种经过验证的 Agent 模式——Router(路由)、Parallel(并行)、Orchestrator(编排)等。mcp-agent 的核心理念是: 这些模式应该是可组合的, 而不是硬编码的。
mcp-agent 由 Lastmile AI 团队开发维护, 这是一家专注于 AI 工程化的初创公司, 创始团队来自 Google DeepMind 和 Anthropic。其使命是降低 AI 应用落地的工程门槛, 让开发者专注于业务逻辑而非基础设施。mcp-agent 是他们为解决「如何用 MCP 构建生产级 Agent」这一具体问题而交出的答卷。
可以把 MCP 理解为 AI 领域的 USB 接口: 以前每接一个设备都要专门的驱动, 现在有了统一标准, 插上就能用。MCP (Model Context Protocol) 由 Anthropic 主导提出, 是一个让大语言模型与外部数据源、工具进行标准化交互的协议。目前支持的文件系统、GitHub、Slack、数据库等工具, 都有对应的 MCP Server 实现。
mcp-agent 的核心价值在于: 它完整实现了 MCP 协议, 并且帮你管理这些 MCP Server 的生命周期。连接、认证、断开、重连这些繁琐的事情, 你无需操心。mcp-agent 内置了 GitHub、Google Drive、Slack 等常见服务的 MCP Server 示例, 开箱即用。
mcp-agent 提供三大核心能力:
1. 全链路 MCP 支持 — 管理 MCP Server 连接生命周期, 支持 stdio 和 HTTP 两种通信方式, 自动处理认证(API Key、OAuth2、Bearer Token)。内置了 GitHub、Google Drive、Slack 等常见服务的 MCP Server 示例, 开箱即用。
2. 可组合的工作流模式 — mcp-agent 实现并组合了 6 种经过验证的 Agent 设计模式:
3. 持久化工作流(Temporal) — 对于需要长时间运行、可能中断的 Agent 流程(如处理用户退款请求), mcp-agent 可接入 Temporal 实现「暂停-恢复-重试」, 无需修改 Agent 代码。这解决了 AI Agent 领域一个长期痛点: 当 LLM 调用超时时, 整个流程就得重来。Temporal 的介入让 Agent 流程真正变得可靠。
图1: mcp-agent 项目 Logo
mcp-agent 的源码结构(src/mcp_agent/)体现了明确的分层设计:
app.py — 全局应用上下文, 管理工作流生命周期, 是用户入口agents/ — Agent 抽象定义, 包含 AgentSpec 声明式配置, 支持 YAML 驱动workflows/ — 6 种工作流模式的实现: router、parallel、orchestrator、evaluator_optimizer、intent_classifier、swarm、deep_orchestratormcp/ — MCP 协议客户端, 管理 Server 连接生命周期server/ — 将 Agent 发布为 MCP Server(自举能力), Agent 也可以成为其他 Agent 的工具executor/ — 任务执行引擎, 支持 asyncio 原生执行和 Temporal 持久化执行tracing/ — OpenTelemetry 可观测性集成, 支持 Anthropic 和 OpenAI 自动插桩oauth/ — OAuth2 认证管理, 支持 GitHub OAuth 等第三方登录cli/ — 命令行工具(mcp-agent), 提供交互式 Agent 运行体验eval/ — 评测相关模块data/ — 内置示例和模板数据技术栈方面, 项目以 Python 3.10+ 为基础, 主要依赖包括: mcp(协议实现)、fastapi(HTTP 服务)、pydantic(配置校验)、opentelemetry(链路追踪)、temporalio(可选, 持久化工作流)、scikit-learn(意图分类)。可选扩展(extra)支持 Anthropic、OpenAI、Google GenAI、Cohere、LangChain、CrewAI、Bedrock、Vertex 等主流 LLM 和 Agent 框架。
图2: Orchestrator(编排器)工作流模式 — 主 Agent 动态分解任务并协调子 Agent
图3: Parallel(并行)工作流模式 — 多 Agent/工具同时执行再汇总
图4: Router(路由)工作流 — 根据意图分发到不同处理路径
安装只需一行命令:
pip install mcp-agent
# 或使用 uv
uv add mcp-agent
最小示例(来自官方 README):
import asyncio
from mcp_agent.app import MCPApp
async def main():
app = MCPApp()
async with app.run():
result = await app.agent('my_agent').run(
instruction='帮我查一下今天北京的天气'
)
print(result)
asyncio.run(main())
所有示例都放在 examples/ 目录下, 涵盖: 基础 Agent、多 Provider(Anthropic/OpenAI/Google/Cohere 等)、Temporal 持久化、LangChain 集成、CrewAI 协作、人机交互、OAuth 认证、Tracing 可观测性等 15+ 个场景。每个示例都可通过 uv run main.py 直接运行。
mcp-agent 本身是纯 Python 库, 没有 Web UI 和 Docker 支持, 部署难度极低。只要有 Python 3.10+ 环境, uv add mcp-agent 即可完成安装。它非常适合集成到现有的 Python 项目或 CI/CD 流程中。
# 开发环境
uv sync --all-extras --all-packages --group dev
# 代码质量
make lint # 自动修复 lint 问题
make tests # 运行测试
make coverage # 覆盖率报告, 要求 >= 80%
硬件要求极低: 不需要 GPU, 512MB RAM 即可运行, 推荐磁盘空间 200MB。适合部署在 Serverless 环境或边缘节点上。
mcp-agent 也存在一些需要正视的局限:
1. MCP 协议尚在演进 — MCP 协议本身仍在快速迭代中(当前 mcp 包版本 ~1.20.0), API 稳定性不能完全保证, 升级可能导致兼容性问题。
2. 文档质量参差不齐 — 虽然有完整的 API 文档和示例, 但高级用法(如 Temporal 集成、OAuth 自定义)的说明仍然偏少, 踩坑成本不低。
3. 生态仍在早期 — 相比 LangChain、AutoGen 等成熟框架, mcp-agent 的社区规模较小, 第三方 MCP Server 的质量也需要自行评估。
4. 调试成本 — 当 Agent 进入多步推理循环时, trace 和 log 的可读性仍有提升空间, 复杂工作流的调试可能比较耗时。
mcp-agent 的出现, 反映了 AI Agent 领域的一个趋势: 从「能不能做」到「怎么做才可靠」。MCP 协议解决了工具调用的标准化问题, mcp-agent 则在这个基础上填补了「如何组织多个工具调用」「如何保证 Agent 运行的可控性」这些工程化空白。
截至目前, mcp-agent 在 GitHub 上拥有超过 8300 颗星, 846 个 Fork, 持续活跃的 Discord 社区。随着 MCP 协议被更多厂商采纳, mcp-agent 这类框架的价值会进一步凸显。如果你正在探索如何用 MCP 协议构建可靠的 AI Agent, mcp-agent 是一个值得关注的项目。它用简洁的 API 封装了复杂的工程问题, 让「构建 Agent」这件事变得触手可及。