mcp-agent

用 MCP 和简单流程模式，快速搭建可靠 AI 智能体。

mcp-agent 是一个基于 Python 的框架，用于构建高效 AI 智能体。它利用 Model Context Protocol (MCP) 作为标准接口，连接各种工具和数据源，并通过简单的工作流模式（如顺序执行、条件分支）编排智能体行为。该项目解决了 AI 应用中工具集成复杂、流程编排繁琐的问题，提供简洁的 API 和类型提示，让开发者能快速搭建可复用的智能体。核心能力包括：MCP 客户端管理、多工具调用、工作流定义、错误处理与重试机制。它特别适合需要与外部系统（如数据库、API）交互的自动化任务，并支持流式输出和异步操作。

开源 free 开源模型

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 8554

维护状态低维护

是否开源是

定价模式 free

项目数据

分类开源模型

开发团队lastmile-ai

所属国家

官网地址

GitHubhttps://github.com/lastmile-ai/mcp-agent

定价模式free

价格说明开源项目，Apache-2.0 许可证，完全免费，可自行部署使用。

访问状态

是否开源是

开源协议Apache-2.0

主要语言Python

技术栈/模型agents,ai,ai-agents,llm,llms,mcp,model-context-protocol,python

GitHub 星标★ 8554

30天Star增速

HF 下载量

上线时间2024-12-18 00:00:00

最近更新2026-09-22 00:00:00

维护状态低维护

中文支持

访问方式

移动端支持

综合评分

收录时间2026-08-09

浏览次数3

使用教程

难度：入门约 10 分钟部署方式：库/依赖 7 步

环境要求

Python 环境（README 推荐用 uv 管理 Python 项目）
uv 或 pip 包管理器
Node.js/npx（filesystem MCP 服务器通过 npx 启动）
至少一个 LLM 提供商的 API Key（如 OpenAI）

安装与启动步骤

1安装 mcp-agent

在项目目录中用 uv 添加依赖；若不用 uv，可改用 pip install mcp-agent 安装。
```
uv add "mcp-agent"
```
2安装 LLM 扩展包

按需安装 LLM 提供商的可选依赖，示例中一次性列出 openai、anthropic、google、azure、bedrock。
```
uv add "mcp-agent[openai, anthropic, google, azure, bedrock]"
```
3获取示例项目

已克隆仓库可跳过本步直接进 examples 目录；也可用 uvx 生成一个基础模板项目到 my-first-agent。
```
uvx mcp-agent init --template basic --dir my-first-agent
```
4进入示例目录

切换到基础示例目录，里面包含 main.py、配置文件和密钥示例文件。
```
cd examples/basic/mcp_basic_agent
```
5创建密钥文件

从示例文件复制出 mcp_agent.secrets.yaml，随后填入真实 API Key，该文件不要提交到代码仓库。
```
cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml
```
6修改配置文件

编辑 mcp_agent.config.yaml，把 filesystem 服务器参数里的换成你要访问的真实目录，并按需改 default_model。
7运行示例

用 uv 运行 main.py，智能体会连接 fetch 与 filesystem 两个 MCP 服务器并调用 LLM 完成查询。
```
uv run main.py
```

关键配置

配置项	必填	说明	示例
`execution_engine`	是	指定执行引擎，示例值为 asyncio。	`asyncio`
`logger.level`	否	日志级别，调试时可设为 debug 查看工具与调用信息。	`debug`
`logger.transports`	否	日志输出方式，可选 console 或同时输出到 file。	`[console]`
`mcp.servers.fetch.command`	否	fetch 服务器的启动命令，示例用 uvx 拉起 mcp-server-fetch。	`uvx`
`mcp.servers.filesystem.args`	否	filesystem 服务器启动参数，末尾需填入允许访问的目录。	`["-y", "@modelcontextprotocol/server-filesystem", "`
`openai.default_model`	否	OpenAI 默认模型，示例为 gpt-4o。	`gpt-4o`

如何确认成功

运行后日志打印 Tools available 工具列表，并输出 README.md 内容、博客段落和 128 字符推文摘要。

常见问题

Q：API Key 应该写在哪里？

A：写入 mcp_agent.secrets.yaml（可从 mcp_agent.secrets.yaml.example 复制），配置项从该文件、环境变量和 mcp_agent.config.yaml 加载，密钥文件需 gitignore。

Q：除 OpenAI 外还支持哪些模型？

A：README 的可选依赖示例列出了 openai、anthropic、google、azure、bedrock，可通过 pip/uv 的 extras 形式安装对应包。

Q：filesystem 服务器报错怎么办？

A：该服务器通过 npx 启动，需本地有 Node 环境；同时确认配置 args 中的已替换成真实目录路径。

Q：如何部署到云端？

A：先执行 uvx mcp-agent login 登录，再执行 uvx mcp-agent deploy my-agent 部署，用 uvx mcp-agent cloud apps list 查看应用列表。

Q：不想用 YAML 配置怎么办？

A：可以在代码里构造 Settings、MCPSettings、MCPServerSettings 对象，再传给 MCPApp(name=..., settings=settings) 实现动态配置。

注意事项

mcp_agent.secrets.yaml 含 API Key，务必留在本地并加入 .gitignore。
filesystem 服务器参数中的是占位符，必须替换为真实目录才能正常运行。
更多配置、可观测性与云端部署细节见官网文档 docs.mcp-agent.com。

核心亮点

基于 MCP 标准协议，工具集成统一且可扩展
工作流模式简单直观，降低智能体开发门槛
类型提示完善，代码可读性和维护性高

不足之处

依赖 MCP 生态，非 MCP 工具需适配
文档/社区待观察

适用场景

构建需要调用多个 API 的自动化助手
开发企业内部的流程自动化智能体
快速原型验证 AI 智能体工作流

替代项目

LangChain、AutoGen、CrewAI

项目介绍

mcp-agent 是智能体领域的开源项目，由 lastmile-ai 开发，2024 年首次发布。

在全站 13,090 个收录项目中，它的 GitHub 星标数（8,554）位列前 6%，在智能体分类的 2,517 个项目里位列前 6%。

近 41 天，它的 GitHub 星标从 8,502 增加到 8,554，净增 52。

项目已超过三个月没有代码更新，维护节奏明显放缓，最近一次代码更新于 2026-09-22。Apache-2.0 许可证，完全免费，可自行部署使用。

它主要面向的使用场景是：构建需要调用多个API的自动化助手。同类可对比的替代方案包括 LangChain、AutoGen、CrewAI。

上一篇：adk-go

下一篇：git-mcp