用官方 Python SDK 开发 MCP 服务器：三大原语、接入 Claude Code 与 Cursor、结构化输出与 HTTP 部署
按 MCP 官网与 Python SDK v2 官方文档（mcp 2.3.0）：用 MCPServer 写出工具、资源、提示词并用 Inspector 验证，把官方天气服务器接进 Claude Code、Claude Desktop、Cursor、VS Code，再用 Field 约束、结构化输出、ToolError、pytest 和 Streamable HTTP 做成可上线的服务。
入门·3 课时·67 分钟·图文实操
免费学习无需登录
你将学会
- 用 MCPServer 写出工具、资源与提示词
- 用内存客户端和 MCP Inspector 验证服务器
- 把 stdio 服务器接入 Claude Code 与 Cursor
- 排查宿主连不上 MCP 服务器的三类原因
- 用 Field、结构化输出与 ToolError 设计工具
- 用 pytest 测试并以 Streamable HTTP 提供服务
适合谁
- 想把内部 API 接入 Claude Code 的 Python 开发者
- 想自己写 MCP 工具的 AI 编程用户
- 从 v1 FastMCP 迁移到 SDK v2 的团队
课前准备
- 会用终端与基础 Python（类型注解、async）
- 本机 Python 3.11+ 与 uv
- Claude Code、Cursor 或 VS Code 任一宿主
课程目录
3 课时 · 67 分钟- 01第一个 MCP 服务器：工具、资源、提示词与 Inspector用 uv 安装 mcp 2.3.0，写出同时含工具、资源模板、提示词的 server.py，先用内存 Client 把三种原语各调一次，再用 MCP Inspector 点一遍，最后改用 Streamable HTTP 运行并读出服务器声明的能力。图文20 分钟开始本课
- 02官方天气服务器：自测后接入 Claude Code、Claude Desktop、Cursor 与 VS Code按 MCP 官网教程写出查询美国天气的 weather.py，记住 stdio 服务器不能往 stdout 打印，用宿主同款启动命令和 Python 客户端自测，再接入 Claude Code、Claude Desktop、Cursor、VS Code，并学会从三处排查连接失败。图文25 分钟开始本课
- 03参数约束、结构化输出、错误处理、pytest 与 Streamable HTTP写一个书店服务器，用 Field 给参数加范围约束、用返回类型生成输出 Schema，对比 ToolError、MCPError 与普通异常，写两条 pytest 测试，再用 Streamable HTTP 在 3001 端口提供服务并让 Claude Code 通过 URL 连接。图文22 分钟开始本课
课程说明
MCP（Model Context Protocol，模型上下文协议）是让 AI 应用连接外部工具和数据的开放协议。Claude Code、Claude Desktop、Cursor、VS Code 等「宿主」都内置了 MCP 客户端：你写好一个 MCP 服务器，把启动命令告诉宿主，它就能调用你的工具。2026 年 10 月，官方 Python SDK 已经进入 v2 稳定线（PyPI 包名 mcp，当前 2.3.0），服务器类是 MCPServer，客户端类是 Client。很多旧教程里的 FastMCP 写法和 SSE 传输都已经过时。
本课完全按 MCP 官网和 Python SDK 官方文档整理，代码与官方示例一致；第 3 课的书店示例由官方 Tools、Structured Output、Handling errors 几页的片段合成。2026-10-25 用 mcp 2.3.0 + Python 3.13 实跑了每段代码，「对照结果」都是真实输出；只有宿主界面里的显示效果（Claude Code 的 /mcp 面板、Cursor 设置页），取自官方文档的描述。共 3 课时：
| 课时 | 你会做完的事 | 需要什么 |
|---|---|---|
| 1 | 用 uv 建项目，写出同时有工具、资源、提示词的服务器，用内存客户端、Inspector 和 HTTP 客户端各验证一次 | Python 3.11+、uv |
| 2 | 按官方教程写天气服务器，先模拟宿主自测，再接入 Claude Code、Claude Desktop、Cursor、VS Code，并排查连不上的情况 | 任一宿主应用 |
| 3 | 用 Field 约束参数，用返回类型生成结构化输出，分清 ToolError 和 MCPError，写 pytest，再用 Streamable HTTP 提供服务 | 同上 |
适合：想把内部 API、数据库或脚本接进 Claude Code / Cursor 的 Python 开发者，在用 AI 编程工具、想自己写 MCP 工具的工程师，以及手里还是 v1 FastMCP 旧代码、准备迁移的团队。
先修：会用终端和基础 Python（函数、类型注解、async）；本机装好 uv，Python 3.11 及以上；第 1 课的 Inspector 需要 Node.js 22.19+。
官方来源：
- MCP 官网「Build an MCP server」：https://modelcontextprotocol.io/docs/develop/build-server
- Python SDK 文档首页：https://py.sdk.modelcontextprotocol.io/
- Installation：https://py.sdk.modelcontextprotocol.io/get-started/installation/
- First steps：https://py.sdk.modelcontextprotocol.io/get-started/first-steps/
- Connect to a real host：https://py.sdk.modelcontextprotocol.io/get-started/real-host/
- Testing：https://py.sdk.modelcontextprotocol.io/get-started/testing/
- Tools：https://py.sdk.modelcontextprotocol.io/servers/tools/
- Structured Output：https://py.sdk.modelcontextprotocol.io/servers/structured-output/
- Handling errors：https://py.sdk.modelcontextprotocol.io/servers/handling-errors/
- Running your server：https://py.sdk.modelcontextprotocol.io/run/
- Client transports：https://py.sdk.modelcontextprotocol.io/client/transports/
- Claude Code「Connect Claude Code to tools via MCP」：https://code.claude.com/docs/en/mcp
- SDK 源码与示例：https://github.com/modelcontextprotocol/python-sdk
绑定工具： Claude Code（/tools/claude-code/）· PyPI https://pypi.org/project/mcp/