MCP开发-02.Python框架选型

发表于 | 分类于
对比 Python 侧 MCP Server 开发框架：官方 SDK、FastMCP、底层 mcp.server、客户端桥接与 Agent 编排，并给出选型决策树与环境约定。

本系列：00 什么是 MCP · 01 协议与心智模型 · 02 Python 框架选型（本文） · 03 部署与调用 · 04 重任务与优化 · 05 从 0 开发 · 06 进阶示例 · 07 阿里云案例

1. 本文范围

聚焦 Python 实现 MCP Server 时的框架与库选择。Client 侧（在 Agent 里连接 MCP）与 Server 侧（暴露 Tools）目标不同，下文分表说明，避免把「编排框架」误当作「Server 框架」。

环境管理建议与 Python-环境管理-uv-心智模型与实践 对齐：项目级 .venv、pyproject.toml 声明依赖、Host 配置里写 Python 绝对路径。

2. Server 开发框架对比

框架 定位 优势 劣势 适用
官方 MCP Python SDK（pip install "mcp[cli]"，FastMCP） 规范参考实现；FastMCP 1.0 正并入官方仓库 与 spec 同步、文档权威；stdio / Streamable HTTP 内置；装饰器 @mcp.tool() 上手快 Tasks 等 cutting-edge 特性跟进中；合并期 API 可能有小幅变动 默认首选
FastMCP 2.x（pip install fastmcp，过渡期独立包） 社区增强层，后并入官方 Tasks（task=True）、Middleware、OAuth、OpenAPI 导入、Storage 后端 需 pin 版本；与官方 SDK 职责重叠，长期应迁移到 mcp 包 生产需 Tasks / 中间件 / 认证
底层 mcp.server 手写 Server、自行注册 handler 完全控制消息流；可嵌入 Starlette/FastAPI 样板代码多；需自行处理 schema 与传输 定制传输、嵌入现有 ASGI 应用
OpenAPI → MCP（FastMCP from_openapi 等） 由 REST 规范生成 Tool 快速包装既有 HTTP API 语义可能粗粒度；需审查生成的 Tool 描述 存量 API 快速暴露

段末注释：ASGI（Asynchronous Server Gateway Interface）是 Python 异步 Web 服务器与应用之间的标准接口；FastMCP 是基于装饰器的 MCP Server 高层 API，现已成为官方 Python SDK 的推荐入口。

3. Client / 编排侧（消费 MCP，非写 Server）

项目 角色 优势 劣势 适用
LangChain MCP Adapters 把 MCP Server 当作 LangChain Tool 与 LangGraph / LCEL 集成 不实现 Server Agent 工作流消费多个 MCP
mcp-agent（LastMile AI） Agent + 多 MCP 工作流 多 Server 组合、工作流抽象 抽象较重、学习曲线 多工具编排、研究原型
OpenAI Agents SDK Agent 运行时 MCPServerStdio 等即用 绑定 OpenAI 生态为主 OpenAI Agent 产品链
Google ADK Agent 开发套件 含 MCP 集成 谷歌栈导向 Gemini / ADK 项目
fast-agent-mcp 轻量 Agent + MCP 工具调用、采样等 社区规模小于 LangChain 快速 Agent 实验

若你的目标是 「写一个给 Cursor 用的工具服务」，应优先 官方 SDK / FastMCP 写 Server，而非从上表选框架。

4. 选型决策树

1
2
3
4
5
6
7
8
9
10
11
flowchart TD
  Start["需要 Python MCP Server?"]
  Start --> Q1{"仅本地 IDE\nstdio 调试?"}
  Q1 -->|是| A1["官方 SDK FastMCP\n+ stdio"]
  Q1 -->|否| Q2{"远程 / 团队共享?"}
  Q2 -->|是| A2["官方 SDK\n+ streamable-http"]
  Q2 -->|否| Q3{"长任务 / Tasks\n/ OAuth?"}
  Q3 -->|是| A3["FastMCP 2.14+\n或官方 SDK 跟进版"]
  Q3 -->|否| Q4{"嵌入现有 FastAPI?"}
  Q4 -->|是| A4["底层 mcp.server\n+ ASGI mount"]
  Q4 -->|否| A1
场景 推荐
第一个 Tool、本地 Cursor / Claude Desktop 官方 SDK + transport="stdio"
内网 HTTPS、多用户 官方 SDK + streamable-http
分钟级任务 + 进度 + 取消 FastMCP task=True 或外部队列（见 04）
已有 OpenAPI 文档的 REST 服务 FastMCP OpenAPI 导入 + 人工审查 Tool
Serverless（Lambda / Workers） 官方 SDK + 无状态 HTTP（见 03）

5. 官方 SDK 与 FastMCP：如何理解合并

2025 年底起，FastMCP 1.0 并入 modelcontextprotocol/python-sdk。实践上：

1
2
# 当前推荐 import（官方 SDK）
from mcp.server.fastmcp import FastMCP

过渡期内，若文档或旧项目仍使用独立包：

1
2
# 过渡期：独立 fastmcp 包（功能更全，长期迁移至 mcp）
from fastmcp import FastMCP  # pip install fastmcp

建议：新项目 pip install "mcp[cli]" 或 uv add mcp；需要 Tasks / 高级中间件 且官方版尚未覆盖时，再额外 fastmcp 并 pin 版本，关注 release note。

6. 环境约定（uv / venv）

6.1 用 uv 初始化项目

1
2
3
4
uv init mcp-demo && cd mcp-demo
uv add "mcp[cli]"
# 可选：长任务场景
# uv add fastmcp

6.2 Host 配置为何要用绝对路径

stdio 模式下 Host 不会激活你的 shell 环境。command: "python" 常指向系统解释器，导致 ModuleNotFoundError: mcp。

正确做法：command 指向项目 .venv/bin/python（macOS/Linux）或 .venv\Scripts\python.exe（Windows）的绝对路径。示例见 05 从 0 开发。

6.3 版本与协议

  • Python：3.10+（以 SDK pyproject.toml 为准）。
  • 协议实践主干：2025-11-25（见 01）。

7. 嵌入 FastAPI / Starlette（模式说明）

不重依赖新框架时，常见模式是：MCP 传输挂载到 ASGI 应用的路由，业务逻辑仍写在 FastMCP 或底层 handler 中。思路：

  1. 用 FastMCP 定义 Tools。
  2. 通过 SDK 提供的 Streamable HTTP / SSE 适配器 挂载到 /mcp。
  3. 同一进程可同时提供 REST 健康检查（/health）与 MCP 端点。

具体 API 以当前 python-sdk 文档 为准；选型动机是「与现有 Web 服务共进程」，而非必须用 FastAPI 才能写 MCP。

8. 小结

问题 答案
默认选什么？ 官方 MCP Python SDK + FastMCP
何时用 FastMCP 2.x 独立包？ Tasks、OAuth、OpenAPI 等官方版尚未满足时
何时用底层 mcp.server？ 定制传输、深度嵌入 ASGI
Agent 里连 MCP 用什么？ LangChain Adapters、mcp-agent 等 Client 侧库
环境怎么配？ 项目 .venv + Host 里 Python 绝对路径

下一步：03 部署方式与调用配置 · 动手：05 从 0 开发

-------------本文结束感谢您的阅读-------------