Python MCP SDK入门 FastMCP快速开发我第一次写 MCP 服务端用的是低级 API注册工具要写一堆装饰器初始化要手动拼 InitializationOptions跑起来还得自己管 stdio 流。后来换成 FastMCP同样的功能代码量少了七成。这篇把 FastMCP 的装饰器 API、生命周期管理、配置体系讲清楚再跟低级 API 做个对比最后给一个完整可运行的项目。FastMCP 是什么FastMCP 是 MCP Python SDK 提供的高层封装让你用装饰器把普通 Python 函数变成 MCP 工具、资源、提示。它自动处理协议握手、消息路由、参数校验和 schema 生成你只管写业务函数。它有两个来源容易搞混。一个是官方 mcp SDK 自带的mcp.server.fastmcp装pip install mcp就有导入写法是from mcp.server.fastmcp import FastMCP。另一个是社区演进的独立包fastmcpFastMCP v2装pip install fastmcp导入写法是from fastmcp import FastMCP功能更全多了标签过滤、服务端组合、代理、后台任务等能力。两者装饰器 API 基本一致本篇用官方自带的版本保证最低依赖。装饰器 API 三件套FastMCP 用三个装饰器对应 MCP 的三类原语。mcp.tool把函数变成工具模型可以调用它执行操作。函数名当工具名docstring 当描述类型注解自动生成参数 schema。返回值会被序列化成文本返回给模型。mcp.resource把函数变成资源模型读取它获取上下文数据。支持静态 URI 和带参数的模板 URI模板用花括号占位比如notes://{note_id}占位符会自动映射成函数参数。mcp.prompt把函数变成提示模板给模型提供结构化的交互起点。返回字符串或消息列表复杂场景可以返回多轮消息。生命周期管理服务端启动和关闭时常要做资源初始化和清理比如连数据库、建连接池。FastMCP 用 lifespan 机制处理传一个异步上下文管理器给FastMCP构造函数。lifespan 在服务端启动时进入yield 出来的对象会挂到请求上下文里工具函数通过ctx.request_context.lifespan_context取到。服务端关闭时执行 finally 里的清理逻辑。用 dataclass 定义上下文类型能让 IDE 自动补全这就是官方说的类型安全上下文。配置管理FastMCP 的配置分三层。构造函数参数管服务级行为比如 name、instructions、dependencies、lifespan。run 方法的参数管传输比如 transport、host、port、log_level。独立包 fastmcp 还支持全局配置通过FASTMCP_前缀的环境变量设置日志等级、错误脱敏、资源前缀格式等。几个常用配置点。instructions 是给客户端和模型看的服务端说明写清楚有哪些能力、怎么用很多人漏写导致模型瞎调工具。dependencies 声明部署时要装的第三方包配合mcp install自动安装。重复注册同名工具时on_duplicate_tools 控制是警告、报错还是覆盖生产环境建议设成 error 尽早发现问题。与低级 SDK API 的对比低级 API 在mcp.server.lowlevel里给你完全的协议控制权代价是要写更多样板代码。下面这张表对比两者。维度FastMCP 高层 API低级 SDK API工具注册mcp.tool一行搞定server.list_tools()加server.call_tool()分开写Schema 生成类型注解自动生成手动构造 types.Tool参数校验框架自动做自己解析校验生命周期lifespan 装饰器风格同样支持 lifespan但要手动拼 InitializationOptions传输启动mcp.run()一行手动 stdio_server 加 server.run 加 InitializationOptions协议控制框架托管定制有限完全可控能改任何细节适合场景业务功能开发协议研究、自定义扩展、特殊传输选型很简单。写业务服务端用 FastMCP几行代码跑起来。要做协议级定制或研究 MCP 内部机制再改用低级 API。两者也能混用FastMCP 内部就是基于低级 Server 实现的。完整代码先装依赖。pipinstallmcp[cli]完整项目note_server.py一个笔记服务包含工具、资源、提示和生命周期管理。# note_server.py# FastMCP 完整示例笔记服务演示工具/资源/提示/生命周期/配置fromcontextlibimportasynccontextmanagerfromcollections.abcimportAsyncIteratorfromdataclassesimportdataclass,fieldfrommcp.server.fastmcpimportFastMCP,Context# ---------- 生命周期上下文定义 ----------dataclassclassNoteStore:笔记存储演示 lifespan 管理的资源。 真实项目换成数据库连接或 ORM 会话。 notes:dict[str,str]field(default_factorydict)defadd(self,note_id:str,content:str)-None:添加一条笔记。self.notes[note_id]contentdefget(self,note_id:str)-str|None:按 id 取笔记不存在返回 None。returnself.notes.get(note_id)deflist_all(self)-list[str]:返回所有笔记 id。returnlist(self.notes.keys())# 类型安全的 lifespan 上下文IDE 能补全 db 字段dataclassclassAppContext:store:NoteStoreasynccontextmanagerasyncdefapp_lifespan(server:FastMCP)-AsyncIterator[AppContext]:服务端生命周期启动时建存储关闭时清理。 yield 出去的对象会挂到每个请求的上下文里 工具函数通过 ctx.request_context.lifespan_context 取用。 # 启动阶段初始化资源storeNoteStore()# 预置两条示例笔记方便验证store.add(1,学习 MCP 传输层)store.add(2,写完 FastMCP 示例)try:# 把资源交给请求处理阶段yieldAppContext(storestore)finally:# 关闭阶段清理资源这里存储在内存里无需特殊清理store.notes.clear()# ---------- 创建服务端 ----------# instructions 写清楚服务能力帮模型正确调用mcpFastMCP(NoteServer,instructions这是一个笔记服务可以添加、查询、列出笔记还能生成摘要提示。,lifespanapp_lifespan,)# ---------- 工具 ----------mcp.tool()defadd_note(note_id:str,content:str,ctx:Context)-str:添加一条笔记。 Args: note_id: 笔记唯一标识 content: 笔记内容 ctx: 框架注入的上下文 # 从 lifespan 上下文取存储对象store:NoteStorectx.request_context.lifespan_context.store store.add(note_id,content)returnf已添加笔记{note_id}mcp.tool()deflist_notes(ctx:Context)-str:列出所有笔记 id。store:NoteStorectx.request_context.lifespan_context.store idsstore.list_all()# 没有笔记时给个友好提示ifnotids:return当前没有笔记return笔记列表: , .join(ids)# ---------- 资源 ----------mcp.resource(notes://{note_id})defget_note(note_id:str,ctx:Context)-str:按 id 读取笔记内容URI 模板的占位符自动映射成参数。store:NoteStorectx.request_context.lifespan_context.store contentstore.get(note_id)# 笔记不存在时返回提示文本ifcontentisNone:returnf笔记{note_id}不存在returncontent# ---------- 提示 ----------mcp.tool()defsummarize_all_notes(ctx:Context)-str:汇总所有笔记内容供模型生成摘要。store:NoteStorectx.request_context.lifespan_context.store# 拼接所有笔记内容parts[f[{nid}]{store.get(nid)}fornidinstore.list_all()]ifnotparts:return没有笔记可汇总return\n.join(parts)mcp.prompt()defreview_notes()-str:生成一个提示让模型审查所有笔记并给出改进建议。return请读取所有笔记逐条审查内容给出简短改进建议。# ---------- 启动 ----------if__name____main__:# 默认 stdio 传输可被 Claude Desktop 等客户端接入# 想换远程传输改成 mcp.run(transportstreamable-http, port9000)mcp.run()客户端note_client.py连接服务端验证全部功能。# note_client.py# 笔记服务客户端验证工具/资源/提示都能用importasynciofrommcpimportClientSession,StdioServerParametersfrommcp.client.stdioimportstdio_clientasyncdefmain():# 配置 stdio 子进程参数paramsStdioServerParameters(commandpython,args[note_server.py],)# 拉起服务端子进程并建立会话asyncwithstdio_client(params)as(read,write):asyncwithClientSession(read,write)assession:# 初始化握手awaitsession.initialize()# 列出工具确认注册成功toolsawaitsession.list_tools()print(工具:,[t.namefortintools.tools])# 调用 list_notes 看预置数据r1awaitsession.call_tool(list_notes,{})print(初始笔记:,r1.content[0].text)# 添加一条新笔记r2awaitsession.call_tool(add_note,{note_id:3,content:测试新增笔记})print(r2.content[0].text)# 读取资源验证 URI 模板resawaitsession.read_resource(notes://3)print(读取 notes://3:,res.contents[0].text)# 调用汇总工具r3awaitsession.call_tool(summarize_all_notes,{})print(汇总:\n,r3.content[0].text)# 获取提示模板promptawaitsession.get_prompt(review_notes)print(提示:,prompt.messages[0].content.text)if__name____main__:asyncio.run(main())效果验证用 Inspector 快速可视化验证会打开调试界面。mcp dev note_server.py在 Inspector 里能看到 NoteServer 的工具、资源、提示三类内容。调用 add_note 添加笔记再读notes://3资源能看到刚写的内容说明 lifespan 上下文在请求间正确共享。跑客户端脚本验证端到端。python note_client.py输出会依次显示工具列表、初始笔记、新增结果、资源读取、汇总内容和提示模板证明工具、资源、提示、生命周期全部跑通。常见问题与避坑1. lifespan 上下文取不到。早期我以为直接ctx.lifespan_context就能取结果属性不存在。正确写法是ctx.request_context.lifespan_context取到的就是你 yield 出去的对象。如果你 yield 的是 dataclass用属性访问yield 的是 dict用键访问。两种别搞混。2. 同步工具阻塞事件循环的误判。FastMCP 默认把同步工具丢到线程池跑不会阻塞事件循环多个工具能并发。但如果你用了有线程亲和性的库比如 Windows 的 COM 组件线程池里跑会出错这时要传run_in_threadFalse让它在事件循环线程跑。这个参数只有独立包 fastmcp 支持。3. 装饰器加不加括号。新版mcp.tool和mcp.tool()都能用。但低级 API 里server.list_tools()必须加括号混用两套 API 时容易写错。统一加括号最保险。4. 重复注册工具名静默覆盖。默认重复注册同名工具只警告不报错线上可能悄悄用错了实现。生产环境把 on_duplicate_tools 设成 error注册阶段就拦住。5. instructions 漏写模型瞎调。instructions 是服务端的能力说明客户端会把它交给模型。不写的话模型只能靠工具描述猜经常调错。花两句话写清楚服务干什么、有哪些主要工具调用准确率明显提升。小结FastMCP 把 MCP 服务端开发做到装饰器级别工具资源提示各一个装饰器生命周期用 lifespan配置分构造参数和 run 参数三两下搞定。日常业务用高层 API协议级定制再回到低级 API。把 instructions 写好、lifespan 上下文取对、重复注册设成报错能避开大部分坑。这四篇连起来从通知机制、传输层、协议对比到 SDK 实操MCP 的核心链路就串完了。
Python MCP SDK入门 FastMCP快速开发我第一次写 MCP 服务端用的是低级 API注册工具要写一堆装饰器初始化要手动拼 InitializationOptions跑起来还得自己管 stdio 流。后来换成 FastMCP同样的功能代码量少了七成。这篇把 FastMCP 的装饰器 API、生命周期管理、配置体系讲清楚再跟低级 API 做个对比最后给一个完整可运行的项目。FastMCP 是什么FastMCP 是 MCP Python SDK 提供的高层封装让你用装饰器把普通 Python 函数变成 MCP 工具、资源、提示。它自动处理协议握手、消息路由、参数校验和 schema 生成你只管写业务函数。它有两个来源容易搞混。一个是官方 mcp SDK 自带的mcp.server.fastmcp装pip install mcp就有导入写法是from mcp.server.fastmcp import FastMCP。另一个是社区演进的独立包fastmcpFastMCP v2装pip install fastmcp导入写法是from fastmcp import FastMCP功能更全多了标签过滤、服务端组合、代理、后台任务等能力。两者装饰器 API 基本一致本篇用官方自带的版本保证最低依赖。装饰器 API 三件套FastMCP 用三个装饰器对应 MCP 的三类原语。mcp.tool把函数变成工具模型可以调用它执行操作。函数名当工具名docstring 当描述类型注解自动生成参数 schema。返回值会被序列化成文本返回给模型。mcp.resource把函数变成资源模型读取它获取上下文数据。支持静态 URI 和带参数的模板 URI模板用花括号占位比如notes://{note_id}占位符会自动映射成函数参数。mcp.prompt把函数变成提示模板给模型提供结构化的交互起点。返回字符串或消息列表复杂场景可以返回多轮消息。生命周期管理服务端启动和关闭时常要做资源初始化和清理比如连数据库、建连接池。FastMCP 用 lifespan 机制处理传一个异步上下文管理器给FastMCP构造函数。lifespan 在服务端启动时进入yield 出来的对象会挂到请求上下文里工具函数通过ctx.request_context.lifespan_context取到。服务端关闭时执行 finally 里的清理逻辑。用 dataclass 定义上下文类型能让 IDE 自动补全这就是官方说的类型安全上下文。配置管理FastMCP 的配置分三层。构造函数参数管服务级行为比如 name、instructions、dependencies、lifespan。run 方法的参数管传输比如 transport、host、port、log_level。独立包 fastmcp 还支持全局配置通过FASTMCP_前缀的环境变量设置日志等级、错误脱敏、资源前缀格式等。几个常用配置点。instructions 是给客户端和模型看的服务端说明写清楚有哪些能力、怎么用很多人漏写导致模型瞎调工具。dependencies 声明部署时要装的第三方包配合mcp install自动安装。重复注册同名工具时on_duplicate_tools 控制是警告、报错还是覆盖生产环境建议设成 error 尽早发现问题。与低级 SDK API 的对比低级 API 在mcp.server.lowlevel里给你完全的协议控制权代价是要写更多样板代码。下面这张表对比两者。维度FastMCP 高层 API低级 SDK API工具注册mcp.tool一行搞定server.list_tools()加server.call_tool()分开写Schema 生成类型注解自动生成手动构造 types.Tool参数校验框架自动做自己解析校验生命周期lifespan 装饰器风格同样支持 lifespan但要手动拼 InitializationOptions传输启动mcp.run()一行手动 stdio_server 加 server.run 加 InitializationOptions协议控制框架托管定制有限完全可控能改任何细节适合场景业务功能开发协议研究、自定义扩展、特殊传输选型很简单。写业务服务端用 FastMCP几行代码跑起来。要做协议级定制或研究 MCP 内部机制再改用低级 API。两者也能混用FastMCP 内部就是基于低级 Server 实现的。完整代码先装依赖。pipinstallmcp[cli]完整项目note_server.py一个笔记服务包含工具、资源、提示和生命周期管理。# note_server.py# FastMCP 完整示例笔记服务演示工具/资源/提示/生命周期/配置fromcontextlibimportasynccontextmanagerfromcollections.abcimportAsyncIteratorfromdataclassesimportdataclass,fieldfrommcp.server.fastmcpimportFastMCP,Context# ---------- 生命周期上下文定义 ----------dataclassclassNoteStore:笔记存储演示 lifespan 管理的资源。 真实项目换成数据库连接或 ORM 会话。 notes:dict[str,str]field(default_factorydict)defadd(self,note_id:str,content:str)-None:添加一条笔记。self.notes[note_id]contentdefget(self,note_id:str)-str|None:按 id 取笔记不存在返回 None。returnself.notes.get(note_id)deflist_all(self)-list[str]:返回所有笔记 id。returnlist(self.notes.keys())# 类型安全的 lifespan 上下文IDE 能补全 db 字段dataclassclassAppContext:store:NoteStoreasynccontextmanagerasyncdefapp_lifespan(server:FastMCP)-AsyncIterator[AppContext]:服务端生命周期启动时建存储关闭时清理。 yield 出去的对象会挂到每个请求的上下文里 工具函数通过 ctx.request_context.lifespan_context 取用。 # 启动阶段初始化资源storeNoteStore()# 预置两条示例笔记方便验证store.add(1,学习 MCP 传输层)store.add(2,写完 FastMCP 示例)try:# 把资源交给请求处理阶段yieldAppContext(storestore)finally:# 关闭阶段清理资源这里存储在内存里无需特殊清理store.notes.clear()# ---------- 创建服务端 ----------# instructions 写清楚服务能力帮模型正确调用mcpFastMCP(NoteServer,instructions这是一个笔记服务可以添加、查询、列出笔记还能生成摘要提示。,lifespanapp_lifespan,)# ---------- 工具 ----------mcp.tool()defadd_note(note_id:str,content:str,ctx:Context)-str:添加一条笔记。 Args: note_id: 笔记唯一标识 content: 笔记内容 ctx: 框架注入的上下文 # 从 lifespan 上下文取存储对象store:NoteStorectx.request_context.lifespan_context.store store.add(note_id,content)returnf已添加笔记{note_id}mcp.tool()deflist_notes(ctx:Context)-str:列出所有笔记 id。store:NoteStorectx.request_context.lifespan_context.store idsstore.list_all()# 没有笔记时给个友好提示ifnotids:return当前没有笔记return笔记列表: , .join(ids)# ---------- 资源 ----------mcp.resource(notes://{note_id})defget_note(note_id:str,ctx:Context)-str:按 id 读取笔记内容URI 模板的占位符自动映射成参数。store:NoteStorectx.request_context.lifespan_context.store contentstore.get(note_id)# 笔记不存在时返回提示文本ifcontentisNone:returnf笔记{note_id}不存在returncontent# ---------- 提示 ----------mcp.tool()defsummarize_all_notes(ctx:Context)-str:汇总所有笔记内容供模型生成摘要。store:NoteStorectx.request_context.lifespan_context.store# 拼接所有笔记内容parts[f[{nid}]{store.get(nid)}fornidinstore.list_all()]ifnotparts:return没有笔记可汇总return\n.join(parts)mcp.prompt()defreview_notes()-str:生成一个提示让模型审查所有笔记并给出改进建议。return请读取所有笔记逐条审查内容给出简短改进建议。# ---------- 启动 ----------if__name____main__:# 默认 stdio 传输可被 Claude Desktop 等客户端接入# 想换远程传输改成 mcp.run(transportstreamable-http, port9000)mcp.run()客户端note_client.py连接服务端验证全部功能。# note_client.py# 笔记服务客户端验证工具/资源/提示都能用importasynciofrommcpimportClientSession,StdioServerParametersfrommcp.client.stdioimportstdio_clientasyncdefmain():# 配置 stdio 子进程参数paramsStdioServerParameters(commandpython,args[note_server.py],)# 拉起服务端子进程并建立会话asyncwithstdio_client(params)as(read,write):asyncwithClientSession(read,write)assession:# 初始化握手awaitsession.initialize()# 列出工具确认注册成功toolsawaitsession.list_tools()print(工具:,[t.namefortintools.tools])# 调用 list_notes 看预置数据r1awaitsession.call_tool(list_notes,{})print(初始笔记:,r1.content[0].text)# 添加一条新笔记r2awaitsession.call_tool(add_note,{note_id:3,content:测试新增笔记})print(r2.content[0].text)# 读取资源验证 URI 模板resawaitsession.read_resource(notes://3)print(读取 notes://3:,res.contents[0].text)# 调用汇总工具r3awaitsession.call_tool(summarize_all_notes,{})print(汇总:\n,r3.content[0].text)# 获取提示模板promptawaitsession.get_prompt(review_notes)print(提示:,prompt.messages[0].content.text)if__name____main__:asyncio.run(main())效果验证用 Inspector 快速可视化验证会打开调试界面。mcp dev note_server.py在 Inspector 里能看到 NoteServer 的工具、资源、提示三类内容。调用 add_note 添加笔记再读notes://3资源能看到刚写的内容说明 lifespan 上下文在请求间正确共享。跑客户端脚本验证端到端。python note_client.py输出会依次显示工具列表、初始笔记、新增结果、资源读取、汇总内容和提示模板证明工具、资源、提示、生命周期全部跑通。常见问题与避坑1. lifespan 上下文取不到。早期我以为直接ctx.lifespan_context就能取结果属性不存在。正确写法是ctx.request_context.lifespan_context取到的就是你 yield 出去的对象。如果你 yield 的是 dataclass用属性访问yield 的是 dict用键访问。两种别搞混。2. 同步工具阻塞事件循环的误判。FastMCP 默认把同步工具丢到线程池跑不会阻塞事件循环多个工具能并发。但如果你用了有线程亲和性的库比如 Windows 的 COM 组件线程池里跑会出错这时要传run_in_threadFalse让它在事件循环线程跑。这个参数只有独立包 fastmcp 支持。3. 装饰器加不加括号。新版mcp.tool和mcp.tool()都能用。但低级 API 里server.list_tools()必须加括号混用两套 API 时容易写错。统一加括号最保险。4. 重复注册工具名静默覆盖。默认重复注册同名工具只警告不报错线上可能悄悄用错了实现。生产环境把 on_duplicate_tools 设成 error注册阶段就拦住。5. instructions 漏写模型瞎调。instructions 是服务端的能力说明客户端会把它交给模型。不写的话模型只能靠工具描述猜经常调错。花两句话写清楚服务干什么、有哪些主要工具调用准确率明显提升。小结FastMCP 把 MCP 服务端开发做到装饰器级别工具资源提示各一个装饰器生命周期用 lifespan配置分构造参数和 run 参数三两下搞定。日常业务用高层 API协议级定制再回到低级 API。把 instructions 写好、lifespan 上下文取对、重复注册设成报错能避开大部分坑。这四篇连起来从通知机制、传输层、协议对比到 SDK 实操MCP 的核心链路就串完了。
