MCP Python SDK 安装指南v2 稳定版的完整安装、依赖解析与 CLI 工具链【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/gh_mirrors/pythonsd/python-sdk导读本文围绕 Model Context ProtocolMCP官方 Python SDKPyPI 包名mcp的安装主题展开覆盖 uv/pip 两种安装方式、Python 3.10 版本要求、v2 稳定版本线的迁移注意事项并逐一解析安装后实际落入环境的每一个依赖包及其职责。读完本文你将掌握如何在开发机与部署环境正确安装 SDK、如何利用mcp[cli]与mcp[rich]两个可选扩展以及安装后如何通过mcp命令行工具验证并驱动自己的服务器。本文以 i18n/de/pages/get-started/installation.md与英文原版 docs/get-started/installation.md 同源为主体并辅以当前仓库的 pyproject.toml 与 CLI 源码 进行源码级佐证。安装前提Python 3.10 与 v2 稳定版本线SDK 以mcp为包名发布在 PyPI 上要求 Python 3.10 及以上版本。这一要求直接体现在仓库根目录 pyproject.toml 的requires-python 3.10声明中同时其打包元数据中的 classifiers 明确列出的支持版本为 Python 3.10、3.11、3.12、3.13 与 3.14。当前文档描述的默认安装目标是v2 版本线即当前稳定发布分支从仓库发布状态与 docs/migration.md 的说明看v2 是带破坏性变更的主版本。v2 相比 v1 在包结构上有一个显著变化协议线类型被拆分到独立的mcp-types发行包详见下文「依赖解析」一节因此 v2 的安装过程与依赖解析行为与 v1 并不完全一致这也是官方文档专门提示迁移注意事项的原因。两种主流安装方式uv 与 pip官方文档给出两种等价安装命令二者安装的均为mcp[cli]含 CLI 扩展的完整版本 uvbash uv add mcp[cli] pipbash pip install mcp[cli] uvuv add mcp[cli]会在当前项目pyproject.toml/uv.lock环境中声明并锁定依赖。由于本仓库本身就是用 uv 管理的工作区见 pyproject.toml 中[tool.uv.workspace]与[tool.uv.sources]的配置uv add是与仓库内建工具链最一致的方式。pippip install mcp[cli]适用于任何标准 Python 环境行为与普通 PyPI 安装一致。两种方式都通过 extras 语法[cli]把命令行工具链一并装入。如果你只想安装 SDK 核心不含 CLI直接使用pip install mcp或uv add mcp即可。从 v1 迁移版本上限约束与迁移指南安装文档专门为仍在使用 v1 的用户给出了明确的版本约束建议v2 是带破坏性变更breaking changes的主版本官方提供了逐项说明的迁移指南。如果你的包依赖mcp且尚未准备好迁移请在依赖声明中保留2的上限例如mcp1.28,2这样未固定unpinned的依赖解析会停留在 1.x 版本线上不会被意外解析到 v2。对应仓库内的完整迁移说明见 docs/migration.md其中详细列出了 v2 的主要破坏性变更包括但不限于FastMCP更名为MCPServer、协议字段由 camelCase 改为 snake_case、httpx/httpx-sse被httpx2取代、mcp.types迁移到独立的mcp-types包等。在动手升级前通读该文档可以大幅降低迁移成本。安装后实际获得的依赖包逐一解析官方文档在「What gets installed」一节中说明了每个依赖的用途。以下结合仓库根目录 pyproject.toml 中[tool.uv-dynamic-versioning]声明的运行时依赖即实际打包进mcp发行版的依赖逐一展开依赖版本要求来自 pyproject.toml职责mcp-types与 mcp 版本完全一致协议线类型请求、结果、内容块作为独立发行包与 SDK 同步版本anyio4.9Python 3.14/4.10Python 3.14异步运行时抽象pydantic2.12.0所有mcp.types模型的基座承担 schema 生成与校验httpx22.5.0Streamable HTTP 与 SSE 客户端传输背后的 HTTP 客户端内建 Server-Sent Events 支持starlette0.27Python 3.14/0.48.0Python 3.14HTTP 服务器传输ASGI 框架层uvicorn0.31.1sys_platform ! emscriptenHTTP 服务器传输ASGI 服务器层sse-starlette3.0.0SSE 服务器端传输python-multipart0.0.9HTTP 服务器传输的表单解析jsonschema4.20.0校验工具的声明式结构化输出pyjwt[crypto]2.10.1OAuth 令牌处理授权流程opentelemetry-api1.28.0轻量级可观测性 APItyping-extensions4.13.0在 Python 3.10 上提供现代类型特性typing-inspection0.4.1类型内省工具pywin32311仅sys_platform win32Windows 平台下stdio子进程管理下面按职责分组做深入说明。mcp-types协议类型独立成包官方文档明确指出每一个协议类型requests、results、content blocks现在都作为独立发行包mcp-types导入名mcp_types发布并与 SDK 严格同步版本mcp-typesmcp 版本精确固定。对依赖mcp的项目来说导入方式完全不变——mcp.types是永久别名逐名镜像mcp_types文档与代码中的每个from mcp.types import ...都通过该别名工作只有在一个只安装mcp-types而不安装完整 SDK的项目里才需要直接import mcp_types。这一设计在仓库源码中可以得到印证src/mcp/types/__init__.py的核心逻辑就是from mcp_types import *并将jsonrpc、methods、version三个子模块逐一镜像绑定保证mcp.types.Tool、mcp.types.version.LATEST_PROTOCOL_VERSION等写法与 v1 完全一致。同时 src/mcp/init.py 顶部直接from mcp_types import (CallToolRequest, ...)再统一__all__导出让from mcp import Tool这样的顶层导入也保持不变。拆分mcp-types的好处在于只做协议序列化/反序列化的轻量工具链无需拖入httpx2、starlette、uvicorn等整套传输栈mcp-types的运行时依赖仅pydantic与typing-extensions见其目录 src/mcp-types/mcp_types 下的pyproject.toml。anyio跨 asyncio/trio 的异步运行时整个 SDK 都是针对 anyio 编写的因此同一套代码可以运行在asyncio或trio之上。这对安装的影响是无论你最终用哪个事件循环anyio 都是强制依赖如果你在测试中需要 trio 支持需要自行额外安装trio仓库开发依赖组中即包含trio0.26.2。httpx2取代 httpx 的新一代 HTTP 客户端v2 用httpx2取代了 v1 的httpx与httpx-sse组合。httpx2是httpx的下一代分支内建了 Server-Sent Events 支持因此独立的httpx-sse依赖被移除。Streamable HTTP 与 SSE 的客户端传输都构建在它之上。从 docs/migration.md 可以看到迁移时通常只需把import httpx改为import httpx2API 兼容但需要注意异常类型、logging.getLogger(httpx)的日志名改为httpx2/httpcore2以及 TLS 校验方式httpx2通过truststore使用操作系统信任库等细节差异。starlette / uvicorn / sse-starlette / python-multipartHTTP 服务器传输栈这四个包共同构成 SDK 的 HTTP服务器端传输能力starlette提供 ASGI 应用框架、uvicorn负责实际起服务、sse-starlette提供 SSE 端点、python-multipart处理 multipart 表单。也就是说如果你只写 MCP客户端而不自建 HTTP 服务器这些包依然会被安装它们是硬依赖但不会被实际使用这是官方文档「什么都不用知道也能用 SDK」的直接体现。jsonschema 与结构化输出jsonschema用于将工具的结构化输出structured output与其声明的输出 schema 进行校验。该能力与 docs/servers/structured-output.md 中讲解的功能直接对应是 v2 类型安全体系的一部分。pyjwt[crypto] 与 OAuth 授权pyjwt[crypto]负责 OAuth 令牌的解析与处理服务于 SDK 的授权authorization能力。相关使用方式可参考 docs/run/authorization.md 与客户端 OAuth 文档 docs/client/oauth-clients.md。opentelemetry-api零成本的可观测性注意这里只引入轻量级的 API 包而不是完整的 OpenTelemetry SDK。官方文档特别强调SDK 的 tracing 中间件因此是零成本的——除非你自己另行安装 OpenTelemetry SDK 与 exporter否则不会产生实际的追踪导出开销。这保证了安装默认不附带任何遥测副作用。完整接入方式见 docs/run/opentelemetry.md。typing-extensions 与 typing-inspection这两个包在 Python 3.10 上补齐现代类型特性如NotRequired、TypeAliasType等是 SDK 严格类型体系仓库以 pyright strict 模式自检见 pyproject.toml 的[tool.pyright]的地基。pywin32仅 Windows 平台的条件依赖pywin32只在 Windows 平台sys_platform win32安装用于管理stdio子进程。在 Linux/macOS 上它不会进入安装结果属于典型的平台条件依赖marker 依赖。可选扩展extrasmcp[cli] 与 mcp[rich]官方文档给出了两个可选扩展其精确版本约束可从 pyproject.toml 的[project.optional-dependencies]中确认mcp[cli]开发必备的命令行工具cli [typer0.16.0, python-dotenv1.0.0]mcp[cli]为mcp命令行工具补齐typerCLI 框架与python-dotenv.env文件加载。装上后即可使用mcp dev、mcp run、mcp install三个子命令详见下文。官方建议开发期间你一定会需要它在已部署的服务器上则可能用不到。mcp[rich]更漂亮的服务器日志rich [rich13.9.4]mcp[rich]引入rich用于美化服务器日志输出。纯体验增强不影响功能。为什么主安装命令总是带 [cli]官方文档示例uv add mcp[cli]与pip install mcp[cli]均默认携带 CLI 扩展这与[project.scripts]中mcp mcp.cli:app [cli]的入口声明一致——mcp命令入口本身就以[cli]为前置条件。若不带[cli]安装后再执行mcpCLI 源码会明确报错提示Install with pip install mcp[cli]见 src/mcp/cli/cli.py 的导入兜底逻辑。安装后验证与使用mcp 命令行工具链安装mcp[cli]后终端中会出现mcp命令。从 src/mcp/cli/cli.py 的源码可以确认其四个子命令及核心参数子命令用途关键参数mcp version打印当前安装的 SDK 版本无mcp dev file在 MCP Inspector 中运行服务器调试用:object后缀指定服务器对象--with-editable/-e可编辑安装目录--with附加安装包mcp run file直接运行 MCP 服务器--transport/-t指定stdio、sse或streamable-httpmcp install file将服务器安装进 Claude 桌面应用--name/-n服务器名--with-editable/-e--with--env-var/-v注入KEYVALUE环境变量--env-file/-f加载.env文件几个与安装主题直接相关的实践要点验证安装运行mcp version会打印形如MCP version x.y.z的输出若包未安装则提示MCP version unknown (package not installed)源码中通过importlib.metadata.version(mcp)实现。服务器文件定位mcp dev/mcp run/mcp install接受file.py或file.py:server_object两种写法不指定对象时按mcp、server、app三个常见变量名依次探测且要求对象是MCPServer类型低层Server暂不支持。开发工作流官方快速入门推荐uv run mcp dev server.py启动 MCP Inspector 进行交互调试具体流程见 docs/get-started/first-steps.mdmcp run适合直接运行服务器mcp install则面向 Claude 桌面应用集成。安装后的下一步安装完成后官方建议的后续路径是对应 docs/get-started/index.md构建你的第一个服务器docs/get-started/first-steps.md连接到真实宿主如 Claude Desktopdocs/get-started/real-host.md用内存客户端为服务器编写测试docs/get-started/testing.md。如果从 v1 升级遇到破坏性问题请回到 docs/migration.md 按「Suggested migration order」逐项处理若需了解依赖如何影响生产部署可参考 docs/run/deploy.md。【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/gh_mirrors/pythonsd/python-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
