<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/modelcontextprotocol/python-sdk) · [上游 README](https://github.com/modelcontextprotocol/python-sdk/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

# MCP Python SDK

<div align="center">

<strong>Model Context Protocol（MCP）的 Python 实现</strong>

[![PyPI][pypi-badge]][pypi-url]
[![MIT licensed][mit-badge]][mit-url]
[![Python Version][python-badge]][python-url]
[![Documentation][docs-badge]][docs-url]
[![Protocol][protocol-badge]][protocol-url]
[![Specification][spec-badge]][spec-url]

</div>

> [!CAUTION]
> **本 README 记录的是 MCP Python SDK v2 —— 一条正在积极开发的预发布（alpha/beta）分支。请勿在生产环境使用 v2。** 预发布版本会发布到 PyPI，包名为 `2.0.0aN` / `2.0.0bN`，且**每个预发布版本相对前一版都可能包含破坏性变更**。请固定精确版本，并在提升版本 pin 时预期需要更新代码。
>
> **v1.x 是唯一稳定的发布分支，仍建议用于生产环境。** 它位于 [`v1.x` 分支](https://github.com/modelcontextprotocol/python-sdk/tree/v1.x)，并继续接收关键 bug 修复和安全补丁；文档见 [v1.x README](https://github.com/modelcontextprotocol/python-sdk/blob/v1.x/README.md)。`pip` 和 `uv` 不会选择预发布版本，除非你显式请求，因此现有安装不受影响。**若你的包依赖 `mcp`，请在稳定版发布前，为版本约束添加上界 `<2`（例如 `mcp>=1.27,<2`）。**
>
> v2 是对 SDK 的一次重大重构，既是为了支持 [2026-07-28 MCP 规范发布](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/)，也是为了修复长期存在的架构问题。变更概览见 [v2 新特性](https://py.sdk.modelcontextprotocol.io/v2/whats-new/)，各项破坏性变更见 [迁移指南](https://py.sdk.modelcontextprotocol.io/v2/migration/)。稳定版 v2 计划于 2026-07-27 与规范同步发布。欢迎试用预发布版本，并[告诉我们哪里会出问题](https://github.com/modelcontextprotocol/python-sdk/issues/new?template=v2-feedback.yaml),，或在 [MCP Contributors Discord 的 #python-sdk-dev](https://discord.gg/6CSzBmMkjX). 频道讨论。

## 文档

**文档地址：<https://py.sdk.modelcontextprotocol.io/v2/>。**

其中包含 [入门指南](https://py.sdk.modelcontextprotocol.io/v2/get-started/),、[v2 新特性](https://py.sdk.modelcontextprotocol.io/v2/whats-new/),、[API 参考](https://py.sdk.modelcontextprotocol.io/v2/api/mcp/),，以及 [迁移指南](https://py.sdk.modelcontextprotocol.io/v2/migration/).。

## 什么是 MCP？

[Model Context Protocol](https://modelcontextprotocol.io)（MCP）让你能够以安全、标准化的方式构建向 LLM 应用暴露数据与功能的服务器。可以把它理解为面向 LLM 交互设计的 Web API。借助本 SDK，你可以：

- **构建 MCP 服务器**，向任意 MCP 主机暴露工具、资源和提示词
- **构建 MCP 客户端**，连接任意 MCP 服务器
- 支持所有标准传输方式：stdio、Streamable HTTP 和 SSE

## 环境要求

Python 3.10+。

## 安装

```bash
uv add "mcp[cli]==2.0.0b1"          # or: pip install "mcp[cli]==2.0.0b1"
```

在 v2 处于预发布阶段时，版本 pin 很重要：未固定版本的安装会解析到最新的稳定版 v1.x，而本 README 并不描述该版本。可在 [PyPI](https://pypi.org/project/mcp/#history) 查看最新预发布版本，一次性命令可使用 `uv run --with "mcp==2.0.0b1"`。

## 15 行代码搭建一个服务器

创建一个 `server.py`：

<!-- snippet-source docs_src/index/tutorial001.py -->
```python
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}!"
```

_完整示例：[docs_src/index/tutorial001.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/docs_src/index/tutorial001.py)_
<!-- /snippet-source -->

这就是一个完整的 MCP 服务器：一个工具、一个模板化资源。在 [MCP Inspector](https://github.com/modelcontextprotocol/inspector): 中打开它。

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

使用 `a=1` 和 `b=2` 调用 `add`，即可得到 `3`。

注意你**没有**编写的内容：没有 JSON Schema（`a: int, b: int` _就是_ schema）、没有请求解析、没有校验代码、没有协议处理。只有两个带类型注解的 Python 函数和一个 docstring。

从这里继续阅读 [入门指南](https://py.sdk.modelcontextprotocol.io/v2/get-started/)。

## 10 行代码搭建一个客户端

同一个包也是完整的 MCP **客户端**。`Client` 可连接到 URL、stdio 子进程、自定义传输层，或（用于测试）直接连接内存中的服务器对象，完全无需传输层：

```python
import asyncio

from mcp import Client

from server import mcp


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


asyncio.run(main())
```

将 `mcp` 替换为 `"http://localhost:8000/mcp"`，同样的代码即可与远程服务器通信。

## 贡献

我们热忱欢迎各经验水平的贡献者参与，并期待你的加入。入门请阅读 [贡献指南](https://github.com/modelcontextprotocol/python-sdk/blob/main/CONTRIBUTING.md)。

## 许可证

本项目采用 MIT License 授权。详见 [LICENSE](https://github.com/modelcontextprotocol/python-sdk/blob/main/LICENSE) 文件。

[pypi-badge]: https://img.shields.io/pypi/v/mcp.svg
[pypi-url]: https://pypi.org/project/mcp/
[mit-badge]: https://img.shields.io/pypi/l/mcp.svg
[mit-url]: https://github.com/modelcontextprotocol/python-sdk/blob/main/LICENSE
[python-badge]: https://img.shields.io/pypi/pyversions/mcp.svg
[python-url]: https://www.python.org/downloads/
[docs-badge]: https://img.shields.io/badge/docs-python--sdk-blue.svg
[docs-url]: https://py.sdk.modelcontextprotocol.io/v2/
[protocol-badge]: https://img.shields.io/badge/protocol-modelcontextprotocol.io-blue.svg
[protocol-url]: https://modelcontextprotocol.io
[spec-badge]: https://img.shields.io/badge/spec-spec.modelcontextprotocol.io-blue.svg
[spec-url]: https://modelcontextprotocol.io/specification/latest