1.1 版本要求与安装方式
1.1 版本要求与安装方式
本节摘要:学一个 SDK,第一步永远是「装对版本」。MCP Python SDK 在版本问题上有一个特别容易踩的坑——
pip install mcp现在默认装的就是 v2,而网上大量旧教程还在用 v1 的FastMCP写法,照抄会直接报错。本节先讲清 Python 版本要求(3.10+),再用一张对照表说清mcp与mcp[cli]两个安装选项的差别——后者多装一个命令行工具,能启动可视化检查器、注册到 Claude Desktop。最后点明依赖解读的关键点。读完本节,你的环境就准备好了。
一、Python 版本要求
这个 SDK 要求 Python 3.10 及以上,官方测试覆盖 3.10 到 3.14。
为什么要卡 3.10?不是因为故意刁难旧版本,而是 SDK 重度依赖 3.10 才稳定下来的几个语言特性:
| 特性 | 用在哪 | 为什么需要 |
|---|---|---|
类型注解进阶(Annotated / X | None) |
工具参数、Resolve 依赖解析 |
第 4、6 章的核心机制都建立在 Annotated[T, ...] 上 |
match 语句 |
协议分发、传输层状态机 | 让协议版本的分支处理更清晰 |
| 性能改进 | 异步 IO 密集的传输层 | 流式 HTTP 长连接对性能敏感 |
💡 技巧:用
python --version先确认。如果你在 3.9 或更早,建议用版本管理工具装一个 3.10+ 的独立环境,而不是升级系统 Python——后者容易搞坏系统工具。
二、两个安装选项:mcp 与 mcp[cli]
SDK 提供两个安装粒度,差别只在「要不要带命令行工具」:
| 安装命令 | 你得到什么 | 适合谁 |
|---|---|---|
pip install mcp 或 uv add mcp |
仅核心库(MCPServer / Client 等) |
只想把 SDK 当库用、自己写启动逻辑 |
pip install "mcp[cli]" 或 uv add "mcp[cli]" |
核心库 + mcp 命令行工具 |
想用检查器调试、一键注册到 Claude Desktop |
[cli] 这个方括号语法叫「可选依赖Extras」,它额外拉进两个包:一个命令行框架、一个环境变量加载器。装了之后你就有了一个 mcp 命令,它提供四个子命令:
mcp dev 在 MCP 检查器里跑你的服务端(本节后文会详讲) mcp run 直接跑你的服务端文件 mcp install 把你的服务端注册到 Claude Desktop mcp version 打印版本
⚠️ 注意:本教程强烈建议第一次装
[cli]版。理由很简单——第 04 节要用的检查器是开发期最顺手的调试工具,而它就靠这个mcp dev命令启动。少了它,你后面调试会很难受。
三、v2 的现状:你装的默认就是新版
这是本节最重要的一句话:
pip install mcp现在装的就是 v2,不是 v1。
v2 是一次大重写,对应 2026-07-28 协议规范。旧版(v1)还在一个独立分支上维护,如果你有存量 v1 代码不想动,需要显式约束版本:
pip install "mcp<2" # 锁在 v1 pip install "mcp>=2" # 显式要 v2(其实不写也是 v2)
v1 → v2 有几个肉眼可见的命名变化,先记住这三个,后面章节会反复提到:
| v1 旧名 | v2 新名 | 一句话差异 |
|---|---|---|
FastMCP |
MCPServer |
高层服务端类改名,装饰器用法基本一致 |
| (无第一类 Client) | Client |
v2 把客户端升级成第一类对象,一行连服务 |
| (无 Resolve) | Resolve |
v2 新增的依赖解析机制,对模型隐藏参数 |
如果你照着网上的旧教程敲 from mcp.server.fastmcp import FastMCP,会直接报找不到模块——这就是 v2 的信号。本教程正文一律用 v2 写法,迁移差异集中在附录。
四、依赖解读:SDK 拉进了什么
装 mcp 时会拉进一批依赖,理解它们有助于你预判 SDK 的能力边界:
核心库依赖(精选) ├── anyio 异步抽象层,让 SDK 同时兼容 asyncio 与 trio ├── httpx2 HTTP 客户端,流式 HTTP 传输的底座 ├── pydantic 类型校验与 Schema 生成,"类型即契约"的引擎 ├── starlette ASGI 框架,流式 HTTP 服务端的基础 ├── uvicorn ASGI 服务器,实际跑 HTTP 服务 ├── jsonschema JSON Schema 校验 └── mcp-types 协议类型定义(独立包,跨客户端/服务端共用)
这里有个值得注意的工程决策:mcp-types 被拆成了独立的包,而不是藏在 mcp 里。为什么?因为协议类型需要被客户端和服务端同时、一致地引用——把它独立出来,两端共用同一份类型定义,就不会出现「服务端改了类型,客户端没跟上」的割裂。这个设计会在第 2 章讲模块分层时再展开。
💡 技巧:如果你用
uv(Anthropic 推荐的包管理器),它会自动处理这些依赖;用pip也没问题,但建议在一个虚拟环境里装,避免污染全局。
本节要点回顾
- Python 版本要求 3.10+,因为 SDK 重度依赖
Annotated等新特性。 - 两个安装选项:
mcp(纯库)与mcp[cli](库 + 命令行工具),第一次装建议带[cli]。 pip install mcp现在默认就是 v2,旧版需用"mcp<2"锁定。- v1 → v2 三大命名变化:
FastMCP→MCPServer、新增第一类Client、新增Resolve。 mcp-types是独立包,供客户端与服务端共用同一份协议类型。- 遇到
FastMCP报错,多半是照了 v1 旧教程,本教程全程用 v2 写法。
装好之后,下一节我们就用十几行代码写出第一个服务端,亲眼看看「类型即契约」是怎么回事。