MCP Python SDK 今日发布

技能简介

MCP Python SDK（mcp）是 Model Context Protocol（模型上下文协议）的官方 Python 实现，由 MCP 官方团队（Linux Foundation 项目）开发和维护。它让 Python 开发者能够以标准化的方式为 LLM 应用提供上下文和工具调用能力，是目前 AI Agent 开发领域最重要的基础设施库之一。

2026 年 9 月 7 日发布的 v2.2.0 是该 SDK 的重大版本迭代，完全重写了架构以支持 2026-07-28 版的 MCP 规范，同时修复了 v1 长期存在的架构问题。

核心能力

• 装饰器驱动的服务器构建：用 @mcp.tool() 装饰器将任意 Python 函数暴露为 MCP 工具，无需编写 JSON Schema 或协议处理代码
• 完整客户端支持：同一包既可做服务端也可做客户端，支持连接任意 MCP 服务器
• 三合一传输层：内置 stdio（本地进程）、Streamable HTTP（远程推荐）和 SSE 三种传输方式
• 类型安全：全面使用 Python 3.10+ 类型提示，函数签名即 Schema，IDE 全链路补全
• 原生异步：基于 asyncio 的全异步架构，支持高并发 MCP 客户端连接
• Elicitation 交互：服务端可向用户发起结构化表单请求和 URL 填写（OAuth、支付等安全流程）
• OpenTelemetry 集成：开箱即用的分布式追踪支持，方便接入监控体系
• CLI 工具：安装 mcp[cli] 后提供 mcp dev、mcp run、mcp install 三个命令，覆盖开发、部署、安装全流程
• 多语言服务端兼容：可与 TypeScript/JavaScript MCP SDK 构建的服务端互操作

安装配置

环境要求

• Python 3.10 及以上
• 推荐使用 uv 包管理器（性能最优），也支持 pip

标准安装（不含 CLI）

uv add mcp 或 pip install mcp

完整安装（含 CLI 工具）

uv add "mcp[cli]" 或 pip install "mcp[cli]"

安装 mcp[cli] 后会新增 mcp 命令行工具，提供 mcp dev（热重载开发）、mcp run（启动服务）、mcp install（安装为本地 MCP 服务器）三个子命令。

使用步骤

第一步：构建一个最简单的 MCP 服务器

创建 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

@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

注意：你没有写任何 JSON Schema、请求解析或协议处理代码——两个类型提示函数加文档字符串，就是完整的 MCP 服务器。

第二步：本地开发调试

在项目目录运行 MCP Inspector（需先安装 mcp[cli]）：

uv run mcp dev server.py

浏览器打开 Inspector UI，可视化调用 add 工具，传入 a=1、b=2，立即得到结果 3。

第三步：部署为远程服务（Streamable HTTP）

将服务器以 HTTP 方式部署，供远程客户端连接：

uv run mcp run server.py --transport streamable-http

服务端默认在 http://localhost:8000/mcp 提供服务，可配置域名、端口和认证。

第四步：编写 MCP 客户端连接服务器

import asyncio
from mcp import Client

async def main() -> None:
    async with Client("http://localhost:8000/mcp") as client:
        result = await client.call_tool("add", {"a": 1, "b": 2})
        print(result.structured_content)  # {'result': 3}

asyncio.run(main())

Client 既可通过 URL 连接远程 HTTP 服务，也可以通过 stdio 启动本地子进程。

适用场景

• AI Agent 工具开发：为 Claude、GPT 等 LLM 构建可复用的工具函数库，通过 MCP 协议暴露给任意支持 MCP 的 AI Host
• 企业内部 AI 集成：将企业私有 API、数据源、业务逻辑封装为 MCP 服务器，让 AI 安全地访问内部系统
• 多 Agent 协作系统：多个 MCP 服务器各自负责不同领域（搜索、数据库、文件处理），通过 MCP 客户端统一编排
• LLM 应用后端：在 LangChain、LlamaIndex 等框架中集成 MCP，作为工具调用层的事实标准
• AI 产品原型开发：使用 mcp dev 快速热重载开发 AI 应用原型，无需关心协议细节
• 跨语言 AI 系统：Python 后端通过 MCP 与 TypeScript 前端 AI 应用互操作，构建全栈 AI 产品

适用人群

• Python 后端开发者：有 Python 基础，想快速为 AI 应用构建工具后端
• AI 应用开发者：使用 LangChain、LlamaIndex 等框架，需要标准化工具调用方案
• AI 产品经理 / 创业者：理解 MCP 协议价值，想搭建企业内部 AI 工具平台
• 全栈工程师：需要打通 Python AI 逻辑与 TypeScript/JS 前端的通信层

工作原理

MCP（Model Context Protocol）是一种专为 LLM 交互设计的应用层协议，类似于 Web API 但针对 AI 场景优化：

1. 工具（Tools）：服务器将 Python 函数以工具形式暴露，LLM 根据用户需求决定调用哪个工具、传什么参数
2. 资源（Resources）：服务器提供只读数据（文件、数据库查询结果等），供 LLM 在生成回答前获取上下文
3. 提示（Prompts）：服务器预定义提示模板，保证用户与 LLM 交互的一致性
4. 传输层：客户端与服务端通过 stdio（本地）或 Streamable HTTP（远程）交换 JSON-RPC 消息

mcp Python SDK 将这些概念封装为简洁的 Python 装饰器和类，开发者用原生 Python 表达意图，SDK 处理所有协议级别的复杂性。

官方链接

• PyPI 地址：https://pypi.org/project/mcp/
• 官方文档：https://py.sdk.modelcontextprotocol.io/
• GitHub 仓库：https://github.com/modelcontextprotocol/python-sdk
• 规范说明：https://modelcontextprotocol.io/
• 问题反馈：https://github.com/modelcontextprotocol/python-sdk/issues