mcp-agent
用 MCP 和可组合工作流构建 Python 智能体应用。
- Star 数
- ★ 8.6k
- 最近更新
- 9 个月前
- License
- Apache-2.0
- 主语言
- Python
- FA 评分
- 53/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Claude.ai · OpenAI API · Claude APIChatGPT（部分支持）
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- Python 后端团队需要让一个研究助手通过 filesystem 和 fetch MCP 服务器读取本地文件、抓取网页并生成摘要时。
- 不适合
- 不愿使用 Python、uv 与 YAML 配置的团队
- 需要生产级持久化执行但不想额外运维 Temporal 服务的团队
- 源码审查
- 53/100 · 缺口较多
这个 Agent 能做什么，适合哪些场景？
mcp-agent 是一个 Python 框架，用于通过 Model Context Protocol（MCP）构建智能体和工作流。其核心运行时 MCPApp 负责加载配置、初始化日志与执行引擎，并管理 MCP 服务器连接的生命周期。Agent 将指令与可调用的 MCP 服务器组合，Augmented LLM 为模型调用补充工具、记忆和结构化输出能力。项目提供并行、路由、编排器-工作者、评估器-优化器和 Swarm 等可组合工作流模式，并可在 asyncio 与 Temporal 执行引擎间切换。应用既可作为独立 Python 程序运行，也能通过 create_mcp_server_for_app 暴露为标准 MCP 服务器；README 还记录了 Cloud 部署路径。
开发者创建 MCPApp，在 mcp_agent.config.yaml 中声明如 fetch、filesystem 的 MCP 服务器，然后定义带有 server_names 的 Agent。进入 async with app.run() 和 async with agent 上下文后，Agent 会初始化服务器连接；调用 agent.attach_llm(OpenAIAugmentedLLM) 可获得 generate、generate_str 和 generate_structured，用模型调用已连接服务器提供的工具。create_parallel_llm、create_router_llm、create_orchestrator 和 create_evaluator_optimizer_llm 等工厂函数可组装更高层流程。将 execution_engine 设为 temporal 后，可配合 create_temporal_worker_for_app 运行持久化工作流；用 create_mcp_server_for_app 则可把 app 的 @app.tool 和工作流输出给 MCP 客户端。
- Python 后端团队需要让一个研究助手通过 filesystem 和 fetch MCP 服务器读取本地文件、抓取网页并生成摘要时。
- 需要按意图把请求分配给不同 AgentSpec、MCP 服务器或函数的应用团队。
- 要把多个专家子任务并行执行、再聚合成一份报告的分析工作流开发者。
- 需要暂停流程等待人工批准或补充信息，并在 Temporal 中恢复执行的业务自动化团队。
- 希望把现有 Python 工具或工作流作为标准 MCP 服务器提供给 Claude Desktop、Cursor 或自定义 MCP 客户端的开发者。
如何安装或部署这个 Agent？
先安装 Python 与 uv。创建项目后执行：
uvx mcp-agent init
uv init
uv add "mcp-agent[openai]"也可使用：
pip install mcp-agentOpenAI 示例需要在 mcp_agent.secrets.yaml 中配置 API 密钥，或设置 OPENAI_API_KEY。若使用其他模型提供商，README 列出可选额外依赖："mcp-agent[openai, anthropic, google, azure, bedrock]"。
如何使用这个 Agent？
创建 main.py，使用 MCPApp、Agent 和 OpenAIAugmentedLLM；在 Agent 中设置 server_names=["fetch", "filesystem"]。在 mcp_agent.config.yaml 中为这两个服务器配置命令及参数，例如 fetch 使用 uvx mcp-server-fetch，filesystem 使用 npx -y @modelcontextprotocol/server-filesystem 和允许访问的目录。随后运行：
uv run main.py最小调用流程是在 async with app.run() 内创建 Agent，在 async with agent 内执行 llm = await agent.attach_llm(OpenAIAugmentedLLM)，再调用 await llm.generate_str("Summarize README.md in two sentences.")。如需生成项目骨架，可使用 uvx mcp-agent init --template basic --dir my-first-agent。
这个 Agent 有哪些优点和局限？
- MCPApp 和 Agent 直接处理 MCP 服务器连接生命周期，应用代码无需自行创建和维护这些连接。
- 同一套工作流注解可用于 asyncio 与 Temporal；切换到 Temporal 后可获得暂停、恢复、重试和持久化历史能力。
- 提供明确的可组合模式工厂，包括并行 Map-Reduce、路由、意图分类、编排器-工作者、评估器-优化器与 Swarm。
- 可将 MCPApp 通过 create_mcp_server_for_app 作为标准 MCP 服务器暴露，便于接入支持 MCP 的客户端。
- 示例以异步 Python、uv 和 YAML 配置为中心；采用其他语言或同步执行模型需要自行集成。
- OpenAI 最小示例依赖 OPENAI_API_KEY 或 secrets 文件；不同模型提供商还需安装对应可选依赖并调整配置。
- Temporal 持久化执行需要将 execution_engine 设为 temporal，并运行额外的 Temporal worker。
- Cloud 部署在 README 中标为 Beta，且其定价、配额与托管运行环境细节未在提供材料中说明。
这个 Agent 与同类方案有什么区别？
与仅作为 MCP 主机的 Claude Desktop 或 Cursor 相比，mcp-agent 也可以作为独立 Python 应用运行，并通过 create_mcp_server_for_app 将自身工具和工作流反向暴露给这些 MCP 客户端。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| mcp-agent 当前 | 53 · 缺口较多 | 开发框架免费 + 模型费 | ★ 8.6k | 9 个月前 | Python | Claude.ai · OpenAI API · Claude API |
| LlamaAgents | 66 · 存在缺口 | 代码库 / SDK免费 + 模型费 | ★ 464 | 今天 | Python | — |
| Agently AI 应用运行时 | 63 · 存在缺口 | 代码库 / SDK免费 + 模型费 | ★ 1.7k | 24 天前 | Python | OpenAI API · Claude API |
| Stripe AI | 50 · 缺口较多 | 代码库 / SDK免费 + 模型费 | ★ 2k | 今天 | TypeScript | Codex · Claude Code · OpenAI API · Claude API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示：框架支持通过server_names限制工具访问，提供human_input_callback机制，配置中明确分离secrets文件，依赖列表包含安全相关库（如opentelemetry），SECURITY.md提供漏洞报告渠道，但未发现自动回滚机制，发布者身份未验证。扣分原因：缺少对权限最小化的明确文档，用户确认机制仅作为可选回调，数据流透明度不足，敏感数据处理细节有限，依赖安全未提供漏洞扫描证据，外部影响未明确说明，回滚机制缺失，来源归属仅依赖作者信息。
证据显示：代码库包含测试文件（如test_agent.py）和CI工作流（checks.yml），依赖版本固定，但失败消息处理未充分展示。扣分原因：自一致性有测试支持但未全面覆盖，依赖可用性有版本锁定但未验证，失败消息仅部分体现。
证据显示：README提供多种使用场景（如MCP server、Temporal、Cloud），明确列出支持的模式和功能，配置灵活，但未明确边界。扣分原因：受众和场景描述充分，能力边界有说明但不够详细，触发精度有示例但未系统化，环境适配有配置示例但未全面。
证据显示：README结构清晰，安装说明详细，命名稳定（如mcp-agent），提供示例和FAQ，许可证为Apache-2.0，版本号在pyproject.toml中，有SECURITY.md和贡献指南。扣分原因：已知限制未明确列出，版本变更日志未提供，维护责任有作者信息但未明确。
证据显示：输出格式有示例（如generate_str），提供多种工作流模式，成本效益有说明（如生产就绪）。扣分原因：输出可用性有示例但未全面，边际价值有说明但未量化，成本效益有描述但未提供具体数据。
证据显示：README中的声明有文档链接，但未提供独立验证。扣分原因：声明可追溯性有限，跨来源验证不足，事实与推断分离不明确。
- 发布者身份未验证，需谨慎评估供应链风险。
- 未发现自动回滚机制，生产环境需自行实现。
- 依赖安全未提供漏洞扫描证据，建议使用前进行安全审计。
- 已知限制未明确列出，可能影响部署决策。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
发布说明摘录
Minor patch update to get mcp-agent compatible with latest MCP package v1.8.0 Changes - Upgrade MCP package dependency to v1.8.0 with corresponding hotfixes (8de63b4) - Add an OllamaAugmentedLLM and ensure it works well with complex workflows that require structured type generation ( - Fixing absolute path of server in basic/decorator/yaml @Deathn0t (#181) - Get rid of custom websocket and stdio clients in favor of default ones shipped in MCP package (9d92ef0)在 GitHub 查看 ↗ -
发布说明摘录
Thank you to all the wonderful community contributions! We are gearing up for a significant update to mcp-agent shortly. You can follow the progress in feature/temporal_prime and feature/app_server branches. v0.0.18 has a few bug fixes, and the ability to specify a custom http client for OpenAI AugmentedLLM (thanks @blevz!) Changes - Add ability to configure the http_client for openai @blevz (#173) 🐛 Bug Fixes - fix: add system prompt handling to AzureAugmentedLLM @StreetLamb (#148) - fx: _reasoning flag used to set api params @Pythonista7 (#139) …在 GitHub 查看 ↗ -
发布说明摘录
Minor release adding proper support for MCP servers using SSE and Websockets, with configurable headers, as well as OpenAI o4 model support. Huge thanks to @pmohan6 especially for adding WS support (with tests), as well as @aloktiagi for quickly adding o4 day-of-launch Changes - feature: support websocket connections and passing in HTTP headers to websockets and SSE connections @pmohan6 (#116) - add support for o4 reasoning models @aloktiagi (#142)在 GitHub 查看 ↗