Python SDK 概览：用官方工具链构建 MCP 服务

Python SDK 概览：用官方工具链构建 MCP 服务

基础概念

如果你把 MCP 当成一套协议，那 Python SDK 就是这套协议在 Python 世界里的“官方施工工具箱”。

它不只是让你“能写一个 Server”，而是把几类关键能力一起包了进来：

• 写 MCP Server
• 写 MCP Client
• 跑 stdio / SSE / Streamable HTTP
• 用 CLI 做开发、安装、调试
• 用测试工具在内存里验证 server 行为

官方 README 对它的定位很直接：这是 MCP 的 Python implementation，而且实现的是完整 MCP specification。

我又核了 PyPI 当前状态：截至 2026-04-11，mcp 包最新版本是 1.27.0，要求 Python >=3.10。

核心要素

这套 SDK 到底覆盖了哪些层

它不是单纯“一个 pip 包”

这就是为什么 Python SDK 对 Python 开发者特别顺手。你不是装了一个“协议模型定义库”，而是装了一整套可直接干活的开发工具。

基础用法

安装方式

官方安装文档给的最基本写法是：

uv add mcp

或者：

pip install mcp

如果你还想用 CLI 工具，官方 README 和 quickstart 都大量使用了：

uv add "mcp[cli]"

一个最小示例长什么样

Python SDK 自己的文档里，最常见的结构就是这样：

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:
    """Get a personalized greeting"""
    return f"Hello, {name}!"


@mcp.prompt()
def greet_user(name: str, style: str = "friendly") -> str:
    """Generate a greeting prompt"""
    return f"Write a {style} greeting for someone named {name}."


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

这个例子本身已经说明 Python SDK 的核心风格：

• 用 Python 函数表达能力
• 用装饰器把能力暴露为 MCP 原语
• 用类型注解和 docstring 帮你生成 schema 与描述

FastMCP 和 MCPServer 的关系

这里要特别说明一下，因为官方仓库文档里两种写法都能看到：

• FastMCP：README 主线和开发工具链支持最强，当前更像默认推荐接口
• MCPServer：在 docs/index 示例里也还能看到，是另一层 API 入口

对大多数第一次接触 MCP 的 Python 开发者，优先学 FastMCP 更稳，因为：

1. 官方 README 的主线示例围绕 FastMCP
2. mcp dev / mcp run 的说明明确主要支持 FastMCP
3. 装饰器和上下文注入体验更顺手

开发期怎么调试

官方 README 的开发模式是：

uv run mcp dev server.py

它还支持：

uv run mcp dev server.py --with pandas --with numpy
uv run mcp dev server.py --with-editable .

这说明 Python SDK 不只是“运行你的 Server”，而是在帮你把开发、依赖和调试串起来。

怎么装到 Claude Desktop

官方 README 还给了安装命令：

uv run mcp install server.py

以及几个高频变体：

uv run mcp install server.py --name "My Analytics Server"
uv run mcp install server.py -v API_KEY=abc123 -v DB_URL=postgres://...
uv run mcp install server.py -f .env

这很实用，因为你不用自己再去手改一层桌面客户端配置。

测试不是补充项，而是 SDK 的正式能力

Python SDK 的 docs/testing.md 明确提到：可以用 Client(app, raise_exceptions=True) 配合 in-memory transport 测服务端。

一个最小测试长这样：

import pytest
from mcp import Client

from server import app


@pytest.fixture
def anyio_backend():
    return "asyncio"


@pytest.fixture
async def client():
    async with Client(app, raise_exceptions=True) as c:
        yield c


@pytest.mark.anyio
async def test_add_tool(client: Client):
    result = await client.call_tool("add", {"a": 1, "b": 2})
    assert result is not None

这件事非常重要，因为它意味着你不必每次都开桌面客户端或 Inspector 才能验证服务端行为。

同类工具对比

如果你的目标是“在 Python 里构建 MCP 能力”，几条常见路线可以这样看：

核心区别：

• Python SDK：是“官方、通用、可持续”的主路线。
• 手写协议层：控制力强，但开发和维护成本高。
• 平台内置工具系统：快，但不具备 MCP 这类跨客户端标准化价值。

常见误区

优劣势分析

思考题

参考资料

1. MCP Python SDK 官方仓库：https://github.com/modelcontextprotocol/python-sdk（查询日期 2026-04-11）
2. MCP Python SDK README：https://github.com/modelcontextprotocol/python-sdk/blob/main/README.md（查询日期 2026-04-11）
3. MCP Python SDK 文档首页：https://github.com/modelcontextprotocol/python-sdk/blob/main/docs/index.md（查询日期 2026-04-11）
4. MCP Python SDK 安装文档：https://github.com/modelcontextprotocol/python-sdk/blob/main/docs/installation.md（查询日期 2026-04-11）
5. MCP Python SDK 测试文档：https://github.com/modelcontextprotocol/python-sdk/blob/main/docs/testing.md（查询日期 2026-04-11）
6. PyPI mcp 包信息：https://pypi.org/project/mcp/（查询日期 2026-04-11）