MCP Python SDK

Model Context Protocol 官方 Python SDK，通过 FastMCP 声明式框架构建标准化 MCP 服务器与客户端。

项目概述#

MCP Python SDK 是 Model Context Protocol 的官方 Python 实现，由 modelcontextprotocol 组织维护（Linux Foundation 项目系列）。提供完整的协议支持与声明式开发框架，用于将内部 API、数据库、文件系统等异构数据源通过统一协议暴露给 Claude、ChatGPT 等任意 MCP 兼容的 AI 客户端。

当前稳定版为 v1.x，main 分支为 v2 pre-alpha。环境要求 Python ≥3.10（支持至 3.14），跨平台运行。

核心能力#

协议原语#

Tools（工具）：让 LLM 执行操作，类似 REST POST，支持副作用；返回值自动基于类型注解生成 schema 并验证
Resources（资源）：向 LLM 暴露数据，类似 REST GET，无副作用
Prompts（提示）：可复用的 LLM 交互模板

FastMCP 高级特性#

Structured Output：支持 Pydantic BaseModel、TypedDict、dataclass 等类型注解自动生成 schema
Lifespan：类型安全的启动/关闭生命周期管理（如数据库连接池）
Context 注入：工具函数通过 Context 参数访问进度上报、日志、会话信息
Progress / Logging / Notifications：长任务进度通知、分级日志
Elicitation：服务器可向用户请求额外输入
Sampling：服务器可请求客户端 LLM 生成文本
Completions：自动补全支持

传输层#

传输方式	说明
stdio	标准输入输出，适合本地进程通信
SSE	Server-Sent Events，HTTP 长连接推送
Streamable HTTP	最新推荐传输方式，支持可恢复流
WebSockets	可选依赖 `mcp[ws]`
ASGI 挂载	可挂载到已有 ASGI 应用（如 FastAPI），支持 host-based 路由和多路径配置
CORS	支持浏览器端客户端

客户端能力#

完整的 MCP 客户端实现，可连接任意 MCP 服务器
客户端侧 OAuth 认证支持
Tool Result 解析工具与 Display Utilities

认证与可观测性#

JWT 认证（PyJWT）与 OAuth 完整认证流程
OpenTelemetry 集成

架构设计#

FastMCP（高层声明式框架，装饰器 API）
    ↓
低层 Server/Client API（精细控制）
    ↓
anyio 异步运行时（兼容 asyncio 与 trio）
    ↓
传输层（stdio / SSE / Streamable HTTP / WebSocket）
    ↓
Starlette + Uvicorn（ASGI HTTP 服务）

源码布局：src/mcp/ 下分 server/（含 FastMCP）、client/、types/（共享类型定义）。

快速开始#

uv add "mcp[cli]"

可选依赖组：mcp[cli]（CLI 工具）、mcp[ws]（WebSocket）、mcp[rich]（Rich 终端输出）。

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Demo", json_response=True)

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

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

@mcp.prompt()
def greet_user(name: str, style: str = "friendly") -> str:
    return f"Please write a warm greeting for {name}."

if __name__ == "__main__":
    mcp.run(transport="streamable-http")

集成 Claude Code：claude mcp add --transport http my-server http://localhost:8000/mcp

调试：npx -y @modelcontextprotocol/inspector 连接到 http://localhost:8000/mcp

适用场景#

构建 MCP 服务器封装企业内部数据源供 AI 助手调用
构建 MCP 客户端开发自主 AI 应用
与 Claude Code、VS Code Copilot、Cursor 等 AI 编码助手直接集成
一次编写、多 LLM 平台复用的统一接口层

质量保障#

100% 测试覆盖率目标（fail_under = 100）
Pyright strict mode 严格类型检查
Ruff lint + format
Pre-commit hooks

待确认信息#

v2（main 分支，pre-alpha）的具体发布时间表未明确
WebSocket 传输在 v2 中的推荐定位未说明
未找到官方性能基准测试数据
v2 Python SDK 与 TypeScript SDK 的功能对齐程度需对比确认