《MCP 入门实战》第 4 课：环境与第一个 MCP Server（Python）

本文收录于专栏AI Agent智能体系列—— 20 课从协议原理到生产部署的 MCP 中文实战课程点击订阅可跟踪后续更新。【摘要】你想写第一个 MCP Server 但不知道从哪下手这课用官方 Python SDK 手把手搭最小 ServerFastMCP 三段结构、mcp.tool() 装饰器、MCP 客户端直连测试。环境用 conda uv 隔离全程命令可照抄跑完你有一个能被宿主调用的真 Server而不是只看懂了概念。阶段 2 上手实战Server / Client / LLM 接入 | 来源【原·03-01 first-server】 | 知识更新至 2026-10当日检索 本机实测关键字MCP Server、Python MCP SDK、FastMCP、mcp.tool装饰器、MCP开发环境、conda环境、MCP最小示例、MCP客户端测试概念讲解4.1 装什么就三样组件作用安装Python 3.10运行环境系统自带或 python.orgmcp包官方 Python SDK写 Server/Clientpip install mcpMCP Inspector可视化调试面板可选第 6 课细讲npx modelcontextprotocol/inspector国内网络下 pip 走清华镜像pip install mcp -i https://pypi.tuna.tsinghua.edu.cn/simple。版本坑2026-10 实测踩到pip install mcp现在装到的是mcp 2.x本机实测 2.3.0它的 Server 类叫MCPServer不是网上绝大多数教程含微软原课里的FastMCP# mcp 1.x 及所有旧教程的写法2.x 里直接 ModuleNotFoundError:frommcp.server.fastmcpimportFastMCP mcpFastMCP(Demo)# mcp 2.x 的正确写法本课程以此为准:frommcp.server.mcpserverimportMCPServer mcpMCPServer(Demo)两个选择都写清楚学新直接用 mcp 2.x本课程全部代码的口径。除改名外主要差异Python 对象字段是 snake_caseinput_schema不是inputSchemaHTTP 模式的 host/port 移到mcp.run()参数里。跟旧教程pip install mcp2钉在 1.x原课代码原样可跑。生态现状2026-10 实查 PyPI官方在双线并行发版——2.0.0 于 2026-07-28 发布与 2026-07-28 规范同日1.x 线同期仍在维护1.30.0 发布于 2026-09-07。也就是说 2.x 是当前最新主线但生态里大量现成 Server 和教程仍是 1.x 写法。两个推论你自己写的 Server放心用 2.x规范层面它就是现行官网/specification/latest已指向 2026-07-28你装的第三方 Server若它钉了mcp2它的运行环境是独立的uvx/npx 各自装依赖与你 Client 用的 mcp 版本不冲突不用管官方迁移指南https://py.sdk.modelcontextprotocol.io/v2/migration/2026-10 检索可达。4.2 最小 Server 的结构一个 MCP Server 就三部分创建实例 → 装饰器注册工具/资源 →mcp.run()启动。装饰器底下SDK 会从函数签名和 docstring 自动生成工具的 JSON Schema——docstring 就是工具的 description是写给你家模型看的 prompt认真写。案例实战电商订单 Server目标写一个含 2 工具 1 资源的 Server然后用官方 Client SDK 真连一遍验证。Server 代码【已实测 2026-10mcp 2.3.0Python 3.10】04_server.pyfrommcp.server.mcpserverimportMCPServer mcpMCPServer(ShopTools)mcp.tool()defadd(a:int,b:int)-int:两数相加returnabmcp.tool()defsearch_orders(keyword:str,max_results:int10)-list[dict]:按关键词搜索订单fake[{id:E20261001001,item:蓝牙耳机,status:已发货},{id:E20260928007,item:蓝牙耳放,status:已签收},{id:E20261003003,item:机械键盘,status:待付款},]hit[oforoinfakeifkeywordino[item]]returnhit[:max_results]mcp.resource(docs://return-policy)defreturn_policy()-str:退货政策文档return# 退货政策\n签收后 7 天内无理由退货运费由商家承担。if__name____main__:mcp.run()# 默认 stdio 模式Client 验证代码【已实测 2026-10】04_client.pyClient 把 Server 拉成子进程走真实 stdio 协议importasynciofrommcpimportClientSession,StdioServerParametersfrommcp.client.stdioimportstdio_clientasyncdefmain():paramsStdioServerParameters(commandpython,args[04_server.py])asyncwithstdio_client(params)as(r,w):asyncwithClientSession(r,w)ass:awaits.initialize()toolsawaits.list_tools()print(TOOLS:,[t.namefortintools.tools])resawaits.call_tool(add,{a:17,b:25})print(add(17,25) ,res.content[0].text)resawaits.call_tool(search_orders,{keyword:蓝牙})print(search_orders(蓝牙) ,res.content[0].text[:120])resrcawaits.read_resource(docs://return-policy)print(resource ,resrc.contents[0].text[:30])asyncio.run(main())实测输出TOOLS: [add, search_orders] add(17,25) 42 search_orders(蓝牙) { id: E20261001001, item: 蓝牙耳机, status: 已发货 } resource # 退货政策 签收后 7 天内无理由退货运费由商家承担。三个要点stdio 模式不用手动起 ServerClient 负责拉起子进程。这就是桌面宿主的配置里只写commandargs的原因第 7 课展开。返回值类型自动序列化search_orders返回list[dict]SDK 自动转 JSON。模型收到的是结构化文本。stdout 只放协议报文在 Server 里print()会污染协议流导致宿主解析失败日志一律print(..., filesys.stderr)。小结环境就三样Python 3.10 /pip install mcp国内加清华镜像/ Inspector可选mcp 2.x 的 Server 类是MCPServer旧教程的FastMCP在 2.x 直接报错跟旧教程就pip install mcp2docstring 即工具描述是模型选工具的依据stdio 模式 Client 拉起 Server 子进程stdout 只走协议日志走 stderr下一课把这个 Server 接上国产大模型让模型自己决定何时调工具——参见第 5 课《第一个 Client 与国产大模型接入》。扩展阅读原课 03-01 first-serverhttps://github.com/microsoft/mcp-for-beginners/tree/main/03-GettingStarted/01-first-servermcp 1.x→2.x 迁移指南https://py.sdk.modelcontextprotocol.io/v2/migration/MCP Python SDK 仓库https://github.com/modelcontextprotocol/python-sdk系列导航本课程全集见专栏AI Agent智能体系列上一课·第 3 课 传输机制下一课·第 5 课 第一个Client与国产大模型接入我的专栏蛋白 / 抗体 / 多肽 / 核酸分子模拟 / 动力学 / 对接药物 / 设计 / 案例AI / Agent / 大模型开源蛋白结构预测分子模拟基础小分子药物设计案例AI Agent系列开源蛋白生成方法实践分子动力学模拟-Amber蛋白药物设计案例化学大模型开源多肽设计模型分子动力学模拟-Gromacs多肽药物设计案例《AI Agent原理与实战》开源多肽性质预测分子动力学模拟-OpenMM开源小分子生成设计CADD中的机器学习模型DNA/RNA药物设计結合自由能开源药代动力学软件高效计算配置siRNA药物设计模型UCSF DOCK系列我胡师兄说药ASO药物设计模型rDock系列 LeDock系列 gnina系列