# MCP Python SDK

Canonical: https://cqbase.net/zh/entry/mcp-python-sdk
Chinese: https://cqbase.net/zh/entry/mcp-python-sdk
English: https://cqbase.net/en/entry/mcp-python-sdk

> 用 Python 写 MCP 服务器和客户端的官方 SDK。

modelcontextprotocol/python-sdk 是官方 Python SDK，MIT 许可，文档在 py.sdk.modelcontextprotocol.io。如果你要自己做一个小服务器，而不是只安装别人的，这是起点。

先跑通文档里的最小服务器，确认你的客户端能列出工具，再加你自己的函数。密钥从环境变量读，不要写进仓库。协议版本和 SDK 版本要一起看。

## 解决什么问题

[modelcontextprotocol/python-sdk](https://github.com/modelcontextprotocol/python-sdk) 是 Model Context Protocol 的官方 Python SDK，用来编写 MCP 服务器和客户端，而不是只安装别人做好的服务器。它可以把工具、资源和提示暴露给兼容 MCP 的宿主，也可以作为客户端连接已有服务器，并支持 stdio、Streamable HTTP 和 SSE 等传输方式。仓库用 MIT 许可发布，并未归档。文档站点是 [py.sdk.modelcontextprotocol.io](https://py.sdk.modelcontextprotocol.io/)。

核验日期为 2026-11-16（Asia/Shanghai）。PyPI 上的当前稳定版是 [mcp 2.3.0](https://pypi.org/project/mcp/)，与 GitHub 最新正式发版 [v2.3.0](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.3.0) 一致；该发版的 `published_at` 是 2026-10-02 22:02 UTC，换算为 2026-10-03 06:02（Asia/Shanghai）。仓库此后仍有推送，最近一次是 2026-11-05 13:38 UTC，即 2026-11-05 21:38（Asia/Shanghai），因此发版之后可能还有尚未打标签的提交。官方文档写明：现在执行 `pip install mcp` 会装到 2.x。v2 把高层服务器类从 `FastMCP` 改名为 `MCPServer`，并实现了 2026-07-28 这一版协议修订。v1.x 仍处于维护，会继续提供关键修复和安全补丁，文档在 [/v1/](https://py.sdk.modelcontextprotocol.io/v1/)。

## 适合谁

适合需要自己写一个小 MCP 服务器，或写一个客户端去连接现有服务器的 Python 开发者。若你只想在 Claude Code、Cursor 或其他宿主里接入现成服务器，应先看该服务器自己的安装说明，不必从本 SDK 起步。

关于 Python 版本，官方材料并不完全一致。2026-11-16 查阅的 GitHub README 正文写的是 “Python 3.11+”；同日的 PyPI 元数据是 `requires_python = ">=3.10"`，项目分类里也包括 3.10 到 3.14，PyPI 页面描述则写 “Python 3.10+”。本次没有在 3.10 上实跑。安装前请同时查看你准备安装的那一版的 README 和 PyPI 元数据；若只想减少不确定性，可先使用 3.11 或更高版本。

## 怎么装

命令来自 2026-11-16 查阅的仓库 README 和 [Get started](https://py.sdk.modelcontextprotocol.io/get-started/)。官方推荐：

```bash
uv add "mcp[cli]"
```

也可以使用：

```bash
pip install "mcp[cli]"
```

`cli` 这个 extra 会附带 `mcp dev`、`mcp run`、`mcp install` 等命令；若你不需要命令行工具，可以只安装 `mcp`。临时运行则可用 `uv run --with "mcp[cli]" mcp ...`，不必先建项目。

如果你维护的库还不能迁到 v2，官方迁移指南建议加上版本上界，例如 `mcp>=1.28,<2`，避免一次未加约束的安装直接跳到 2.x。从 v1 迁移时，最常见的第一处改动是导入路径：`from mcp.server.fastmcp import FastMCP` 在 v2 中已改为 `from mcp.server import MCPServer`。完整对照见 [Migration Guide](https://py.sdk.modelcontextprotocol.io/migration/)。

## 一个实际例子

下面按官方 README 的最小服务器来验证安装。本次没有实跑，因此不把文档里的返回值写成实测结果。

1. 在空目录里创建 `server.py`，使用官方示例中的写法：

```python
from mcp.server import MCPServer

mcp = MCPServer("Demo")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b
```

2. 按上一节安装带 `cli` extra 的 SDK，然后启动 Inspector：

```bash
uv run mcp dev server.py
```

3. 预期效果（来自官方 README，不是本机实测）：在 Inspector 里调用 `add`，参数为 `a=1`、`b=2` 时，文档写明应得到 `3`。请你自己执行并核对，不要把这句话当成已经跑通的记录。
4. Inspector 里能列出工具之后，再接到你实际使用的宿主，并确认该宿主能看到同一批工具。密钥和其他敏感配置从环境变量读取，不要写进 `server.py` 或仓库。若要写自动化测试，官方文档示范了用 `Client(mcp)` 做进程内调用，不必先起端口。

## 常见坑

- 直接复制仍在使用 `FastMCP` 或 `mcp.server.fastmcp` 的 v1 教程。v2 已重命名，常见报错是 `ModuleNotFoundError: No module named 'mcp.server.fastmcp'`。先看[迁移指南](https://py.sdk.modelcontextprotocol.io/migration/)。
- 只看 GitHub README 或只看 PyPI，忽略二者对最低 Python 版本的不同说法。请同时核对，并在你自己的环境里验证。
- 未加版本上界的依赖，在尚未准备好迁到 v2 时被解析到 2.x。官方建议暂时使用 `mcp>=1.28,<2` 这类约束。
- 把 API 密钥或内部地址写进服务器代码。应使用环境变量。
- 假设「最新发版 2.3.0」等于仓库主分支的每一行代码。2.3.0 发布于 2026-10-03，仓库在 2026-11-05 仍有推送；若你需要恰好某一提交，请对照标签与 `main`，不要把未发版改动写成已经发布。
- 传输方式选错：本地调试常用 stdio 或 `mcp dev`；部署时官方示例用 Streamable HTTP。先在 Inspector 里确认工具列表，再接到宿主。

## FAQ

### 现在应该安装哪个版本？

2026-11-16 查阅的 PyPI 和 GitHub Releases 最新正式版都是 2.3.0（2026-10-03 06:02 Asia/Shanghai）。`pip install mcp` 按官方说明会装到 2.x。仓库在该发版之后还有推送，若你要冻结依赖，请明确写出版本号。

### 最低需要哪个 Python 版本？

GitHub README 写的是 3.11+；PyPI 的 `requires_python` 是 `>=3.10`，页面描述也写 3.10+。二者并不一致。本次没有在 3.10 上实跑。请以你安装的那一版元数据为准，或先使用 3.11+。

### `FastMCP` 还能用吗？

在 v2 里，高层服务器类已改名为 `MCPServer`，旧的 `mcp.server.fastmcp` 导入路径按官方迁移说明是去掉而不是继续兼容。新代码请使用 `from mcp.server import MCPServer`。若暂时不迁，应留在 v1.x 维护线。

### 可以继续使用 v1 吗？

可以。官方写明 v1.x 会继续获得关键修复和安全补丁，文档在 `/v1/`。若你发布的库还依赖 v1，请加上 `<2` 这样的上界，避免用户未加约束地安装到 2.x。

### 许可证是什么？怎么确认工具真的注册成功？

仓库和 PyPI 均声明为 MIT License，见 [LICENSE](https://github.com/modelcontextprotocol/python-sdk/blob/main/LICENSE)。确认工具是否注册成功，应先在 MCP Inspector 或官方示范的进程内 `Client` 测试里列出并调用该工具，再接到宿主。本文没有实跑，不编造 Inspector 截图或返回值。

## 来源与许可

仓库 [modelcontextprotocol/python-sdk](https://github.com/modelcontextprotocol/python-sdk) 使用 MIT 许可。本文依据 2026-11-16 查阅的 README、[Get started](https://py.sdk.modelcontextprotocol.io/get-started/)、[What's new in v2](https://py.sdk.modelcontextprotocol.io/whats-new/)、[Migration Guide](https://py.sdk.modelcontextprotocol.io/migration/)、[PyPI mcp 2.3.0](https://pypi.org/project/mcp/) 和 [v2.3.0 发版说明](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.3.0)，用自己的话写成，供 CQBase 上下文库使用。若安装命令或类名有变，以官方文档和 PyPI 为准。

## 收录信息

- 作者: modelcontextprotocol
- 许可证: MIT
- 来源: https://github.com/modelcontextprotocol/python-sdk
- 收录: 2026-11-15
- GitHub 星标: 24868（采集 2026-11-15）

