---
title: "Python SDK 概览：用官方工具链构建 MCP 服务"
wiki: mcp
category: "SDK"
slug: python-sdk-overview
url: https://learnagent.wiki/mcp/cards/python-sdk-overview
tags: ["MCP", "Python SDK", "FastMCP", "MCPServer", "SDK"]
last_updated: 2026-04-11
reading_time: 12
---

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

# 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`。**

### 核心要素

| 要素 | 作用 |
|------|------|
| **FastMCP** | 官方主推的高层开发接口，适合绝大多数 Server 开发场景 |
| **MCPServer / low-level server** | 更底层的接口，适合你需要更细粒度控制协议细节时使用 |
| **Client** | Python SDK 不只能写服务端，也能写客户端和测试 |
| **CLI 工具链** | `mcp dev`、`mcp run`、`mcp install` 这类开发体验工具都在同一生态里 |
| **多传输支持** | stdio、SSE、Streamable HTTP 都是正式支持的一等公民 |

### 这套 SDK 到底覆盖了哪些层

```mermaid
graph TD
    A["Python SDK"] --> B["Server 开发"]
    A --> C["Client 开发"]
    A --> D["CLI 工具链"]
    A --> E["测试能力"]
    B --> B1["FastMCP"]
    B --> B2["low-level server / MCPServer"]
    C --> C1["连接任意 MCP Server"]
    D --> D1["mcp dev / mcp run / mcp install"]
    E --> E1["Client(app) 内存测试"]
```

### 它不是单纯“一个 pip 包”

```mermaid
graph LR
    A["pip / uv 安装 mcp"] --> B["写 Server"]
    A --> C["写 Client"]
    A --> D["调试 Inspector"]
    A --> E["跑测试"]
    A --> F["安装到 Claude Desktop"]
```

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

## 基础用法

### 安装方式

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

```bash
uv add mcp
```

或者：

```bash
pip install mcp
```

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

```bash
uv add "mcp[cli]"
```

### 一个最小示例长什么样

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

```python
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 的开发模式是：

```bash
uv run mcp dev server.py
```

它还支持：

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

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

### 怎么装到 Claude Desktop

官方 README 还给了安装命令：

```bash
uv run mcp install server.py
```

以及几个高频变体：

```bash
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 测服务端。

一个最小测试长这样：

```python
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 | 自己手写协议层 | 只用某个上层应用内置工具系统 |
|------|------------|----------------|------------------------------|
| 是否官方支持 | **是** | 否 | 取决于平台 |
| 覆盖面 | Server、Client、CLI、测试、传输 | 主要只覆盖你自己实现的部分 | 只在单平台里有效 |
| 上手速度 | 快 | 慢 | 快 |
| 可迁移性 | 高 | 高，但成本高 | 低 |
| 适合场景 | 大多数 Python MCP 开发 | 做 SDK / 深度底层实验 | 只在某个平台内快速接功能 |

核心区别：

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

## 常见误区

| 误区 | 准确理解 |
|------|----------|
| 以为 Python SDK 只能写 Server | 不对。官方 README 明确说它也能写 Client |
| 以为安装 `mcp` 后就只有一个库函数可用 | 不是，它还包含传输、CLI、测试等一整套能力 |
| 以为 `mcp dev` 只是个启动别名 | 它是开发调试链路的一部分，不只是“换个命令跑脚本” |
| 以为 FastMCP 和低层接口只是写法风格不同 | 不只是风格差异，开发体验、自动化程度和 CLI 支持范围都有区别 |
| 以为本地 stdio 和生产 HTTP 是同一套思路直接平移 | 不是。官方 README 对生产部署更明确推荐 Streamable HTTP |
| 以为 Python SDK 文档里的所有内容都已经完全成熟定型 | 不是。比如 `docs/concepts.md` 目前就还在 Under Construction 状态，判断时要优先看 README、quickstart 和已落地 examples |

## 优劣势分析

| 优势 | 劣势 |
|------|------|
| **官方主线明确**：README、quickstart、PyPI、examples 基本围绕同一套思路 | **资料层级较多**：README、docs、examples、quickstart 分散着看，初学者容易混 |
| **开发体验完整**：从安装、调试、测试到客户端安装都能在一个 SDK 生态里完成 | **高低层接口并存**：FastMCP、MCPServer、low-level server 会让刚入门的人分不清 |
| **Python 生态兼容性强**：数据处理、脚本自动化、内部 API 集成都很顺 | **部分文档仍在补齐**：不是所有专题页面都像 README 一样完整 |
| **测试友好**：in-memory client 测试很适合工程化开发 | **传输和部署复杂度仍真实存在**：HTTP 生产化不是 SDK 一装就自动解决 |
| **版本和发行渠道清晰**：PyPI、GitHub、文档站都可核实 | **变化仍然存在**：要持续关注 SDK 版本和官方 README 更新 |

## 思考题

<details>
<summary>初级：为什么说 Python SDK 的价值不只是“少写几行协议代码”？</summary>

**参考答案：**

因为它解决的不只是语法糖问题，而是把一整条开发链路标准化了：

- 怎么定义原语
- 怎么跑本地开发
- 怎么接 Inspector
- 怎么装进客户端
- 怎么写测试

如果没有这套 SDK，你不是只会多写几行 JSON-RPC，而是要自己把开发工具链、调试方式和运行方式都搭起来。

</details>

<details>
<summary>中级：为什么官方文档里既出现 `FastMCP`，又出现 `MCPServer`，但新手仍然更适合先学 `FastMCP`？</summary>

**参考答案：**

因为“能用”不等于“当前主线最适合入门”。

从官方 README、`mcp dev` / `mcp run` 的说明、以及 examples 的组织方式来看，FastMCP 更像现在的主开发体验入口。它让你更少关注底层协议，更快拿到可以跑、可以测、可以安装的结果。

所以不是说 MCPServer 不能学，而是顺序上更合理的是：

1. 先用 FastMCP 建立整体感觉
2. 真遇到底层控制需求，再看 low-level / 其他接口

</details>

<details>
<summary>进阶：如果你在团队里推动 Python SDK 做 MCP 开发，最应该先统一的不是“代码风格”，而是什么？</summary>

**参考答案：**

最先统一的通常是工作流，而不是单纯代码风格。

比如：

1. 默认用 `uv` 还是 `pip`
2. 默认用 `FastMCP` 还是允许直接下沉 low-level
3. 本地调试统一走 `mcp dev` 还是 Inspector 手动连
4. 测试统一是否要求 in-memory client 覆盖
5. 最终部署默认是 stdio 还是 Streamable HTTP

这些决定了团队会不会越写越散。Python SDK 提供了很多能力，但真正的工程稳定性来自“团队是否用同一条主路线”。

</details>

## 参考资料

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）

---
*Source: https://learnagent.wiki/mcp/cards/python-sdk-overview*
*Markdown mirror of https://learnagent.wiki, served as text/markdown for LLM ingestion.*