MCP协议实战：用Python 5分钟搭建你的第一个MCP Server（附完整代码）

MCP协议实战用Python 5分钟搭建你的第一个MCP Server附完整代码导读MCP协议Model Context Protocol已经成为AI Agent调用外部工具的事实标准。阿里、腾讯、Google全面支持魔搭MCP广场上线近1500个Server——但全网实操教程依然稀缺。本文用一段可直接运行的Python代码带你从零搭建第一个MCP Server解决Agent想操作数据库/查天气/发邮件却不知道如何标准化接入的痛点。适合有Python基础的开发者阅读附完整报错排查指南。一、为什么MCP协议突然火了2024年11月Anthropic发布了MCP协议初衷很简单让AI Agent连接外部工具时不再需要为每个工具写一套定制化的胶水代码。想象一个场景你的Agent需要查天气、操作数据库、调用GitHub API。以前的做法是——每个API写一段适配代码格式五花八门维护成本高得离谱。MCP协议做的就是统一这件事工具提供方按标准写一个MCP Server任何支持MCP的AgentClaude、GPT、DeepSeek等都能直接调用就像USB接口插上去就能用。2026年MCP已经成了行业共识Anthropic将MCP捐赠给Linux Foundation魔搭MCP广场上线近1500个Server覆盖搜索、地图、支付等领域中国银联通过MCP协议对接加油、充电、停车等支付场景对开发者来说掌握MCP Server开发已经是AI Agent落地的必备技能。二、MCP协议核心概念3分钟搞懂在开始写代码之前先理清三个核心概念MCP Server工具提供方暴露一组标准化的工具Tools、资源Resources和提示词Prompts。MCP ClientAgent端负责发现Server、调用工具、处理返回结果。Transport通信方式支持stdio本地进程和SSEHTTP流生产环境常用SSE。MCP Client调用调用调用AI Agent / LLMMCP Server数据库天气APIGitHub APIMCP协议本质上定义了一套JSON-RPC 2.0的通信规范。开发者不需要关心底层协议细节因为官方SDK已经帮我们封装好了。三、环境准备开始之前确保你的环境满足以下要求依赖项版本要求说明Python 3.10MCP SDK需要3.10pip最新版用于安装依赖安装MCP Python SDKpipinstallmcp验证安装pip show mcp如果输出了包信息Name、Version等说明环境准备就绪。注意mcp模块没有直接暴露__version__属性因此python -c import mcp; print(mcp.__version__)会报AttributeError。使用pip show mcp是更可靠的验证方式。四、5分钟搭建你的第一个MCP Server下面这段代码是一个完整的、可运行的MCP Server示例。它暴露了三个工具计算器、字符串反转、当前时间查询。4.1 编写Server代码创建文件my_first_mcp_server.pyfrommcp.server.fastmcpimportFastMCPimportdatetime# 初始化MCP Server指定名称mcpFastMCP(demo-server)# 工具1加法计算器mcp.tool()defadd(a:float,b:float)-float:计算两个数的和。returnab# 工具2字符串反转mcp.tool()defreverse_string(text:str)-str:将输入字符串反转。returntext[::-1]# 工具3获取当前时间mcp.tool()defget_current_time()-str:返回当前系统时间ISO格式。returndatetime.datetime.now().isoformat()# 启动Serverstdio模式适合本地测试if__name____main__:mcp.run(transportstdio)代码解析FastMCP(demo-server)创建一个MCP Server实例名称会显示在Client的工具列表里。mcp.tool()装饰器将普通Python函数注册为MCP协议工具函数名就是工具名docstring会被Client读取作为工具描述。mcp.run(transportstdio)启动Server使用stdio模式通过标准输入输出通信适合本地调试。4.2 用Client调用验证创建文件test_client.pyfrommcpimportClientSession,StdioServerParametersfrommcp.client.stdioimportstdio_clientimportasyncioasyncdefmain():# 配置Server启动参数server_paramsStdioServerParameters(commandpython,args[my_first_mcp_server.py],)# 建立stdio连接asyncwithstdio_client(server_params)as(read,write):asyncwithClientSession(read,write)assession:# 初始化会话awaitsession.initialize()# 列出所有可用工具toolsawaitsession.list_tools()print( 可用工具列表 )fortoolintools.tools:print(f -{tool.name}:{tool.description})# 调用add工具resultawaitsession.call_tool(add,{a:3,b:5})print(f\n add(3, 5) {result})# 调用reverse_string工具resultawaitsession.call_tool(reverse_string,{text:MCP协议})print(f reverse_string(MCP协议) {result})# 调用get_current_time工具resultawaitsession.call_tool(get_current_time,{})print(f 当前时间 {result})if__name____main__:asyncio.run(main())运行测试python test_client.py预期输出 可用工具列表 - add: 计算两个数的和。 - reverse_string: 将输入字符串反转。 - get_current_time: 返回当前系统时间ISO格式。 add(3, 5) 8.0 reverse_string(MCP协议) 议协PCM 当前时间 2026-07-04T09:15:32.123456 如果看到了上面的输出恭喜你——你的第一个MCP Server已经跑通了。4.3 进阶暴露资源Resource除了工具MCP协议还支持暴露资源。资源是只读的数据适合返回配置信息、文档内容等。在my_first_mcp_server.py中追加importurllib.parse# 暴露一个静态资源Server说明文档mcp.resource(docs://about)defget_about()-str:返回Server的基本信息。return这是一个演示用的MCP Server用于学习MCP协议开发。# 暴露一个动态资源带参数mcp.resource(greeting://{name})defget_greeting(name:str)-str:根据名字返回问候语。decoded_nameurllib.parse.unquote(name)returnf你好{decoded_name}欢迎学习MCP Server开发。资源URI采用scheme://path格式Client可以通过session.read_resource()方法读取。踩坑提醒MCP框架会对Resource路径参数进行URL编码因此如果参数包含中文或特殊字符在Server端需要用urllib.parse.unquote()解码否则会得到%E5%BC%A0%E4%B8%89这样的编码字符串而非张三。五、常见问题与报错排查在MCP Server开发过程中这几个坑我踩过帮你提前规避报错信息 / 问题现象原因解决方案ModuleNotFoundError: No module named mcpMCP SDK未安装或安装在错误环境确认pip install mcp执行成功且Python解释器路径一致AttributeError: module mcp has no attribute __version__mcp包未暴露__version__属性改用pip show mcp查看版本号或直接import mcp验证安装ConnectionClosedError: stdio connection closedServer进程崩溃或未启动检查Server代码是否有语法错误单独运行python my_first_mcp_server.py验证Tool not found: xxx工具名拼写错误或Server未注册确认mcp.tool()装饰器已加且调用时工具名完全一致TimeoutErrorClient等待Server响应超时检查Server是否有死循环或阻塞操作异步函数要正确awaitTypeError: missing required argument调用工具时参数缺失或类型不匹配对照函数签名检查参数名和类型注意int和float的区别Resource路径参数中文乱码显示为%E5%BC%A0%E4%B8%89MCP框架对Resource路径参数自动做了URL编码在Server端用urllib.parse.unquote(name)解码后再使用额外建议生产环境不要用stdio模式改用SSEServer-Sent Events通过HTTP通信便于分布式部署。工具函数的docstring一定要写清楚这直接影响AI Agent理解工具用途的准确性。如果工具执行耗时较长建议在docstring中标注让Agent知道可能需要等待。六、从Demo到生产下一步怎么走跑通上面的代码只是第一步。在实际项目中MCP Server通常会对接真实的外部服务。几个典型的扩展方向数据库MCP Server暴露SQL查询工具让Agent能查业务数据。文件系统MCP Server暴露文件读写工具让Agent能操作本地文件。第三方API MCP Server把公司内部API封装成MCP工具让Agent调用。此外MCP协议支持三种通信模式本文用的是最简单的stdio模式。但当你要把MCP Server部署到生产环境时stdio模式显然不够用——你需要了解SSEServer-Sent Events和HTTP Stream模式才能做出正确的架构选型。我在下一篇文章中会深度对比三种模式stdio本地进程通信适合开发和测试SSE基于HTTP的单向流适合浏览器场景HTTP Stream双向流式传输适合高并发生产环境[推荐阅读MCP协议的三种服务模式深度解析stdio、SSE、HTTP Stream怎么选]发布后将更新链接跑通上面的代码只是第一步。在实际项目中MCP Server通常会对接真实的外部服务。几个典型的扩展方向数据库MCP Server暴露SQL查询工具让Agent能查业务数据。文件系统MCP Server暴露文件读写工具让Agent能操作本地文件。第三方API MCP Server把公司内部API封装成MCP工具让Agent调用。我在后续文章中会逐一拆解这些实战案例包括MySQL/PostgreSQL接入、文件系统权限控制、以及多MCP Server组合使用的架构设计。七、总结本文从一个实际问题出发——AI Agent如何标准化调用外部工具——引出了MCP协议的背景和核心价值。通过一段可直接运行的Python代码我们完成了安装MCP协议Python SDK用FastMCP快速搭建MCP Server注册工具Tool和资源Resource用Client连接并调用验证排查了5个最常见的报错MCP协议正在重塑AI Agent与外部世界的连接方式。2026年掌握MCP Server开发的开发者将在智能体应用落地的浪潮中占据先机。相关阅读MCP协议三种服务模式深度解析stdio、SSE、HTTP Stream选型指南MCP Server安全加固GB/Z 185视角下的四层纵深防御架构智能体互联互通的国家标准发布AI助手终于能互相聊天了GB/Z 185《人工智能 智能体互联》系列标准核心内容梳理你在搭建MCP Server时遇到了什么问题或者你打算用MCP对接什么类型的工具数据库、API、文件系统欢迎在评论区交流我会整理成合集持续更新有价值的提问我会单独出一篇深度分析。如果这篇文章对你有帮助欢迎点赞 收藏。收藏率决定算法推荐权重你的每一次收藏都能让更多开发者看到这篇实战指南。