/ 目录 / 演练场 / MCP Python SDK
● 官方 modelcontextprotocol ⚡ 即开即用

MCP Python SDK

作者 modelcontextprotocol · modelcontextprotocol/python-sdk

Model Context Protocol 官方 Python SDK——30 行代码构建 server 和 client,内置 FastMCP 兼容的装饰器。

Anthropic 官方维护的 MCP Python SDK。提供 server(mcp.server.fastmcp.FastMCP)、client(mcp.client.session.ClientSession)以及更底层的原语。作为规范合规性的权威参考——有疑问时,这里就是真相来源。基于装饰器的 FastMCP API 已从 jlowin/fastmcp 合并进来。

为什么要用

核心特性

实时演示

实际使用效果

mcp-python-sdk.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "mcp-python-sdk": {
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ],
      "_inferred": true
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "mcp-python-sdk": {
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "mcp-python-sdk": {
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ],
      "_inferred": true
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "mcp-python-sdk": {
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ],
      "_inferred": true
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "mcp-python-sdk",
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "mcp-python-sdk": {
      "command": {
        "path": "uvx",
        "args": [
          "--with",
          "mcp",
          "python",
          "-m",
          "mcp.server.example"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add mcp-python-sdk -- uvx --with mcp python -m mcp.server.example

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: MCP Python SDK

10 分钟内用 Python 构建你的第一个 MCP server

👤 MCP 新手 Python 开发者 ⏱ ~15 min beginner

何时使用: 你想将一个 Python 函数暴露给 Claude。

前置条件
  • Python 3.10+ — uv 或 pyenv
步骤
  1. 安装并搭建骨架
    Use uv to install mcp. Create server.py with one tool: get_weather(city) that calls a public API.✓ 已复制
    → 带 @tool 装饰器的 10 行文件
  2. 通过 stdio 运行
    Run mcp dev server.py. Open the MCP Inspector and verify the tool listing.✓ 已复制
    → 工具可从 inspector 调用
  3. 添加到 Claude Desktop
    Add to claude_desktop_config.json. Test from Claude.✓ 已复制
    → 对话中出现实时响应

结果: 可运行的 Python MCP server,已注册到 Claude。

注意事项
  • 在 handler 中使用 print() 会破坏 stdio — 使用 logging 输出到 stderr;永远不要写入 stdout

使用 SDK 的 client 为 MCP server 编写集成测试

👤 将 MCP 发布到生产环境的开发者 ⏱ ~30 min intermediate

何时使用: 你需要能证明 MCP 行为正确的 CI 测试。

步骤
  1. 启动 server
    Use mcp.client.stdio to spawn server.py and call list_tools(). Assert expected names.✓ 已复制
    → 测试通过
  2. 调用每个工具
    For each tool, call with a representative input and assert the output schema.✓ 已复制
    → 所有工具已验证
  3. 接入 pytest
    Convert into pytest fixtures so CI runs them on every PR.✓ 已复制
    → 可复用的测试框架

结果: 有信心工具不会回归的 MCP server。

实时将长运行工具的输出流式传回 Claude

👤 构建构建、部署或长模拟 MCP 的开发者 ⏱ ~45 min advanced

何时使用: 工具需要数分钟,你希望对话中实时显示进度,而非等完成后才显示。

步骤
  1. 使用 streamable HTTP 传输
    Switch from stdio to streamable HTTP. Yield progress events from the tool.✓ 已复制
    → Claude 在执行过程中显示部分输出
  2. 添加取消支持
    Honor cancel requests so user can abort if the tool takes too long.✓ 已复制
    → 取消在运行中途生效

结果: 即使运行缓慢,工具也能给人实时的感觉。

组合

与其他 MCP 搭配,撬动十倍杠杆

mcp-python-sdk + mcp-go-mark3labs

多语言——性能关键部分用 Go,ML/数据部分用 Python

mcp-python-sdk + mcp-registry

将你的 Python MCP 发布到官方注册表

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
FastMCP name, version? 顶层 server 创建 0
@server.tool decorator on async function 每个你想暴露的函数 0
@server.resource decorator with uri pattern 只读数据暴露 0
@server.prompt decorator on prompt builder 可复用的 prompt 模板 0
ClientSession transport 测试或构建 MCP client 0
stdio_server () 本地模式 0

成本与限制

运行它的成本

API 配额
不适用——库
每次调用 Token 数
不适用
费用
免费(MIT 协议)
提示
在 pyproject.toml 中锁定 SDK 版本;规范仍在演进

安全

权限、密钥、影响范围

凭据存储: 由你的工具决定
数据出站: 由你的 handler 控制

故障排查

常见错误与修复

工具未显示

确保 @tool 装饰器加在 async 函数上,且函数在 server 启动前已注册

验证: 运行 `mcp dev server.py` 并打开 inspector
Pydantic 验证错误

工具输入由 Pydantic 验证;检查类型提示是否与 Claude 发送的内容匹配

Server 在 stdin EOF 时挂起

确保你的 async handler 不会死锁——使用 anyio 保证兼容性

替代方案

MCP Python SDK 对比其他方案

替代方案何时用它替代权衡
FastMCP (PrefectHQ)你想要原始第三方 fork 中的额外工具现已大部分合并回来;是一个薄封装
mcp-go (mark3labs)Go 是你的语言不同的生态系统

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills