Model Context Protocol Python SDK 入门指南从零搭建并验证你的第一个 MCP 服务器【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/gh_mirrors/pythonsd/python-sdk本篇指南面向 MCPModel Context Protocol新手也面向刚接触 python-sdk 的开发者系统讲解从安装 SDK、编写第一个服务器、连接真实宿主Host到用内存客户端验证功能的完整路径。读完本文你将掌握uv run mcp dev与内存客户端Client(mcp)两套核心工作流并理解为什么本仓库文档中的每一段示例代码都是可直接复制、可运行、可被测试验证的真实代码。快速上手四条主线路径MCPModel Context Protocol定义了 AI 应用与工具服务器之间的通信协议。python-sdk 是 MCP 协议在 Python 生态下的官方实现仓库地址README.md它同时提供了构建服务器与客户端的完整能力。对于零基础读者官方文档规划了一条从零到可运行的、经过测试的服务器的路径共四步安装 SDK在 Python 3.10 环境中安装mcp包编写第一个服务器用三个装饰器暴露工具、资源和提示词连接真实宿主把服务器接入 Claude Desktop、IDE 等宿主应用测试服务器用内存客户端Client(mcp)无需进程与端口即可验证。这四个页面是入门阶段的唯一主线本文将以这条路径为骨架展开并结合仓库源码与示例文件把每一步背后的实现原理讲透。直接运行文档中的每一段代码入门文档给出一条最重要的使用建议所有代码块都可以直接复制使用它们是完整、可运行的文件。这意味着你不需要脑补缺失的导入、包装或入口代码。具体操作方式把代码块粘贴进一个server.py然后用 MCP Inspector 打开它uv run mcp dev server.pymcp dev是 SDK 自带命令行工具由mcp[cli]可选依赖提供的一个子命令。查看 src/mcp/cli/cli.py 可以看到它的真实行为它先导入目标文件支持file.py:object后缀指定服务器对象然后调用npx启动modelcontextprotocol/inspector再以子进程方式把你的服务器跑起来从而在浏览器中获得一个可视化的调试面板。因此运行该命令的前提是环境中具备 Node.js/npm用于npx以及uv工具链。文档强烈建议你把代码亲手写或复制下来、本地编辑并运行。只有在自己的编辑器里实际操作你才能真正体会到这套 SDK 的设计意图代码量之少、自动补全之智能以及类型检查在运行之前就能拦截错误。示例全部经过测试验证绝非凭空猜测入门页有一个关键承诺你不会靠猜You will not be guessing。这并非空话而是由仓库的工程机制保证的每个文档示例都是仓库中的真实文件所有示例代码位于docs_src/目录下例如入门示例 docs_src/first_steps/tutorial001.py文档页通过--8--语法直接内嵌这些文件每个示例都被 SDK 自身的测试套件执行测试通过一个内存客户端in-memory client来调用示例中的服务器对象。入门页给出了这段验证测试的核心代码import pytest from mcp import Client from server import mcp pytest.mark.anyio async def test_add() - None: async with Client(mcp) as client: result await client.call_tool(add, {a: 1, b: 2}) assert result.structured_content {result: 3}注意这里的关键点没有子进程、没有端口、没有传输层。Client(mcp)直接把mcp这个服务器对象传给了Client类——因为Client内部支持内存连接模式它绕过一切网络协议在进程内直接与服务器对象对话。这与 FastAPI 生态中的TestClient思路一致。正因为如此如果 SDK 的某次改动破坏了某个文档示例CI 会在页面出错之前先变红。你在这里读到的代码就是实际运行的代码。而且这段测试代码不仅服务于文档验证它就是你日后测试自己服务器的方式详见 Testing。文档示例如何组织为了让示例即源码这条链路可追溯仓库按文档章节在 docs_src/ 下建立了一一对应的子目录例如docs_src/first_steps/tutorial001.py第一个服务器的完整示例docs_src/first_steps/tutorial001_client.py与之配对的完整客户端docs_src/testing/tutorial001.py测试章节用的简单计算器服务器。在 tests/docs_src/ 下每个章节都有对应的test_*.py测试文件如 tests/docs_src/test_first_steps.py它们正是文档示例被测试套件守护这一承诺的实现载体。内存测试的关键参数raise_exceptionsTrue在测试场景下Testing 文档推荐一种更完整的写法其中raise_exceptionsTrue值得单独说明pytest.mark.anyio async def test_call_add_tool(client: Client): result await client.call_tool(add, {a: 1, b: 2}) result.meta None assert result snapshot( CallToolResult( content[TextContent(typetext, text3)], structured_content{result: 3}, ) )这个参数只影响工具函数体之外的异常行为当服务器内部发生意外崩溃时出于安全考虑服务器会把它消毒成一条通用的Internal server error再返回给远端调用者避免泄漏内部细节而在测试中你恰恰不希望看到被掩盖的错误raise_exceptionsTrue会让测试看到真实报错信息。注意它不影响工具内部抛出的异常——工具内的异常会正常变成is_errorTrue的结果对象这在 Handling errors 中有完整论述。该参数在测试中应始终开启在生产代码中则没有意义。从示例源码反推 SDK 的核心设计既然示例代码就是仓库源码我们直接以 docs_src/first_steps/tutorial001.py 为例看看一个入门服务器长什么样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 fHello, {name}! mcp.prompt() def summarize(text: str) - str: Summarize a piece of text in one sentence. return fSummarize the following text in one sentence:\n\n{text}这个文件暴露了 SDK 的三个核心设计事实两个导入路径分工明确客户端类从from mcp import Client导入实现位于 src/mcp/client/client.py服务器类则从from mcp.server import MCPServer导入。SDK 刻意不提供from mcp import MCPServer这种捷径。一个装饰器完成全部注册mcp.tool()、mcp.resource(uri)、mcp.prompt()分别是工具、资源、提示词三种原语的唯一注册入口。函数的名称、docstring、类型注解会被自动解析为协议所需的名称、描述与参数 JSON Schema——你无需单独声明任何元数据。{param}即资源模板greeting://{name}中的{name}会绑定到函数同名参数使该资源成为资源模板Resource Template在客户端列表中单独呈现直到调用方提供具体的name值才产生实际资源。配对的客户端示例 docs_src/first_steps/tutorial001_client.py 则展示了另一种用法——通过 URL 连接运行中的服务器并读取它声明的能力capabilitiesasync def main() - None: async with Client(http://localhost:8000/mcp) as client: print(client.server_capabilities.model_dump(exclude_noneTrue))能力capabilities机制是 MCP 协议的关键服务器在连接时声明自己能应答哪些请求族tools/list、tools/call、resources/read、prompts/get等客户端只请求服务器声明过的内容。MCPServer会为你自动声明这三类能力而像completions参数自动补全这类需要额外编写 handler 的能力未注册时就不会出现在声明中规范的客户端也不会贸然发起请求。安装前的知识准备mcp[cli]与 v2 版本线入门路径的第一步是安装这里补充安装文档Installation中的关键事实避免初学者踩坑SDK 以mcp包名发布在 PyPI 上要求Python 3.10官方文档描述的是v2当前稳定主版本。v2 是一次带破坏性变更的大版本若你的项目依赖mcp且暂未迁移应保留2的上界如mcp1.28,2具体变更清单见 Migration Guide开发时推荐安装 CLI 扩展用于mcp dev、mcp run、mcp install三个子命令# uv uv add mcp[cli] # pip pip install mcp[cli]可选扩展mcp[rich]则用于美化服务器日志。SDK 底层依赖mcp-types协议类型、anyio异步运行时支持 asyncio 与 trio、pydantic模型与 Schema 生成、httpx2客户端 HTTP 传输等组件这些细节在正常使用中无需关心。下一步文档是参考手册而非线性课程一旦你的服务器跑起来入门文档明确指出其余文档是参考手册不是课程。每个页面都可以独立阅读你完全可以按需直达。四条主线指向如下服务器能暴露什么工具、资源、提示词→ Servers在你注册的函数内部能用什么上下文、依赖、日志等→ Handlers如何把服务器放到客户端面前stdio、HTTP、已有的 FastAPI 应用→ Run构建使用 MCP 服务器的应用即客户端一侧→ Clients。此外入门路径中的 Connect to a real host 页面展示了接入宿主的统一思路宿主如 Claude Desktop、Claude Code、Cursor、VS Code通过uv run --with mcp[cli] mcp run /absolute/path/to/server.py以子进程方式启动你的服务器全部配置工作本质上只是把这同一个启动命令写到不同宿主的不同配置文件中。而mcp install命令可以自动完成 Claude Desktop 的配置写入。小结入门路径四步走安装 → 第一个服务器 → 连接真实宿主 → 内存测试对应 docs/get-started/ 下的四个页面文档中每个代码块都是 docs_src/ 里的完整文件可用uv run mcp dev server.py直接运行调试每个示例都被 SDK 测试套件通过内存客户端Client(mcp)守护执行CI 先于文档变红因此文档代码可信可复用内存客户端也是你测试自己服务器的标准工具测试时开启raise_exceptionsTrue以便暴露真实异常从 src/mcp/cli/cli.py、src/mcp/client/client.py 到 docs_src/first_steps/仓库源码与文档示例互相印证构成了示例即源码、源码即文档的完整闭环。【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/gh_mirrors/pythonsd/python-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考