cqbase.net · 中英双语

CQBase 上下文库

Context & Query Base

教程

MCP Python SDK

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

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

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

本页是导读,不是原文。

解决什么问题

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

核验日期为 2026-11-16(Asia/Shanghai)。PyPI 上的当前稳定版是 mcp 2.3.0,与 GitHub 最新正式发版 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/。

适合谁

适合需要自己写一个小 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。官方推荐:

uv add "mcp[cli]"

也可以使用:

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。

一个实际例子

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

  1. 在空目录里创建 server.py,使用官方示例中的写法:
from mcp.server import MCPServer

mcp = MCPServer("Demo")


@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b
  1. 按上一节安装带 cli extra 的 SDK,然后启动 Inspector:
uv run mcp dev server.py
  1. 预期效果(来自官方 README,不是本机实测):在 Inspector 里调用 add,参数为 a=1、b=2 时,文档写明应得到 3。请你自己执行并核对,不要把这句话当成已经跑通的记录。
  2. Inspector 里能列出工具之后,再接到你实际使用的宿主,并确认该宿主能看到同一批工具。密钥和其他敏感配置从环境变量读取,不要写进 server.py 或仓库。若要写自动化测试,官方文档示范了用 Client(mcp) 做进程内调用,不必先起端口。

常见坑

  • 直接复制仍在使用 FastMCP 或 mcp.server.fastmcp 的 v1 教程。v2 已重命名,常见报错是 ModuleNotFoundError: No module named 'mcp.server.fastmcp'。先看迁移指南。
  • 只看 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。确认工具是否注册成功,应先在 MCP Inspector 或官方示范的进程内 Client 测试里列出并调用该工具,再接到宿主。本文没有实跑,不编造 Inspector 截图或返回值。

来源与许可

仓库 modelcontextprotocol/python-sdk 使用 MIT 许可。本文依据 2026-11-16 查阅的 README、Get started、What's new in v2、Migration Guide、PyPI mcp 2.3.0 和 v2.3.0 发版说明,用自己的话写成,供 CQBase 上下文库使用。若安装命令或类名有变,以官方文档和 PyPI 为准。

订阅 CQBase 周刊

每周一封,介绍本周新收录的公开 AI 技能、提示词、MCP 和用法。可随时退订。我们不会把邮箱交给第三方作其营销之用。