【GitHub趋势】PrefectHQ/fastmcp：用 Python 快速构建 MCP 服务端与客户端，配 TaoToken 统一 Key 通道

1. 为什么要在 Python 里手搓 MCP 服务端MCP 这个词最近在 AI 应用圈出现的频率越来越高全称是 Model Context Protocol你可以把它理解成「大模型和外部工具、数据之间的一套通用插座标准」。以前想让模型调用你自己的函数得写一堆适配层、参数校验、文档描述现在只要按 MCP 的约定把函数暴露出去支持 MCP 的宿主比如各类 AI 编辑器、Agent 框架就能直接发现并调用它。fastmcp 就是干这件事的 Python 框架来自 PrefectHQGitHub 上两万多 Star。它的定位很直接用接近普通 Web/API 的写法把「一个 Python 函数」变成「可被 LLM 调用的 MCP 工具」。你写一个带类型注解的函数加个装饰器参数校验和工具文档会自动生成要连远程服务端时传输协商、认证、协议生命周期这些脏活它也帮你接管。这篇适合两类人一类是手里有业务函数、想快速暴露给 AI 宿主调用的后端或 AI 应用开发者另一类是要用统一客户端对接多台 MCP 服务的集成方。我会从零把服务端和客户端都跑通再配上 TaoToken 的统一 Key 通道让你不用在多个平台之间来回切 Key。全程可复制踩过的坑我也会标出来。2. TaoToken 前置把 Key 和 API 通道先备好在写代码之前先把「模型调用」这条链路准备好。fastmcp 负责的是工具协议层但工具背后如果还要调大模型就需要一个稳定的 API 入口。TaoToken 在这里的角色是统一 Key 通道一个 Key 走通模型对话、编码、Agent 等场景省得每个工具单独配一套凭证。你需要做三件事。第一注册并登录官网拿到账号https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。第二进控制台创建 API Key地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 创建后立刻复制保存页面刷新后就不再完整显示。第三确认你要用的模型和通道可以在模型对话页先试一句https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。API 的基础地址统一用 https://taotoken.net/api 注意这个地址不带任何查询参数配置时直接填这一串即可。如果你后面要接 Claude Code 这类编码工具走的是 Anthropic 兼容通道文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 接入细节照着文档填就行。提示Key 只存在本地环境变量或配置文件里别硬编码进要提交到 Git 的脚本。我一般用.env加python-dotenv或者直接export到 shell。3. 可复制配置服务端、客户端与 config.toml3.1 安装 fastmcp 并写第一个服务端推荐用 uv速度比 pip 快不少uv pip install fastmcp # 或者 pip install fastmcp装完核对一下版本生产环境建议钉死精确版本因为 MCP 协议演进较快fastmcp version新建server.py这是最小可运行的服务端from fastmcp import FastMCP mcp FastMCP(My MCP Server) mcp.tool def greet(name: str) - str: 根据名字返回问候语 return fHello, {name}! mcp.tool def add(a: int, b: int) - int: 两数相加 return a b if __name__ __main__: mcp.run()mcp.tool装饰器会把函数登记成 MCP 工具类型注解name: str自动变成参数校验docstring 自动变成工具描述。这就是 fastmcp 最舒服的地方——你几乎不用写额外胶水代码。本地跑起来python server.py如果要走 HTTP 远程访问让别的机器或客户端能连fastmcp run server.py:mcp --transport http --port 80003.2 客户端连接与 config.toml 骨架客户端这边fastmcp 也能直接连远程端点。下面是一个client.pyimport asyncio from fastmcp import Client async def main(): async with Client(http://127.0.0.1:8000/mcp) as client: tools await client.list_tools() print(可用工具:, [t.name for t in tools]) result await client.call_tool(greet, {name: TaoToken}) print(调用结果:, result) asyncio.run(main())很多宿主用config.toml或settings.json来登记 MCP 服务端。一个通用的config.toml骨架长这样[mcp_servers.my_server] command python args [server.py] env { TAOTOKEN_API_KEY ${TAOTOKEN_API_KEY} } [mcp_servers.remote_server] url http://127.0.0.1:8000/mcp transport http对应的settings.json骨架Cline、CC Switch 这类工具常用{ mcpServers: { my_server: { command: python, args: [server.py], env: { TAOTOKEN_API_KEY: 你的Key } }, remote_server: { url: http://127.0.0.1:8000/mcp, transport: http } } }在 Cline 里把上面这段贴进 MCP 配置区保存后它会自动拉起服务端进程。CC Switch 同理切换不同 MCP 服务时改mcpServers下的键名即可。如果你要长期跑编码类 Agent建议直接上 Coding Plan通道更稳https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。4. 验证请求确认服务端和客户端真的通了配置写完不算完得验证。分三步走。第一步确认服务端进程活着。启动 HTTP 模式后另开一个终端curl -s http://127.0.0.1:8000/mcp能返回协议相关的响应就说明端口通了。如果连接被拒多半是没加--transport http或者端口被占。第二步跑客户端脚本看工具列表和调用结果python client.py正常输出类似可用工具: [greet, add] 调用结果: Hello, TaoToken!第三步在宿主里验证。以 Cline 为例配置保存后打开 MCP 面板应该能看到my_server处于已连接状态工具列表里出现greet和add。点一下调用返回问候语就说明整条链路通了。如果你还想验证模型侧是否正常回到模型对话页发一句测试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 确认 Key 和通道没问题再回来联调 MCP。5. 本篇常见错排查报错一ModuleNotFoundError: No module named fastmcp装到了别的 Python 环境。用which python和which pip确认解释器一致或者干脆用uv run python server.py让 uv 管理环境。报错二客户端连不上http://127.0.0.1:8000/mcp服务端没起 HTTP 模式。默认mcp.run()走的是 stdio不是 HTTP。远程连接必须显式加--transport http。报错三工具列表为空装饰器写成了mcp.tool()带括号或者函数没有类型注解。fastmcp 靠注解生成 schema缺了注解工具可能注册不上。改成mcp.tool并补全注解。报错四从旧版 pip 升级后异常官方文档提到过旧版本升级偶尔出问题需要按文档加--force-reinstall重装。生产环境务必钉死精确版本号别用浮动版本。报错五宿主里 MCP 显示已连接但调用超时多半是env里的 Key 没传进去或者服务端脚本路径是相对路径、宿主工作目录不对。把args改成绝对路径Key 用环境变量注入。注意涉及认证、访问控制的场景别把服务端直接暴露到公网。本地联调先用127.0.0.1要远程再考虑加认证层。6. 把 Key 通道和 MCP 串成一条线到这里服务端、客户端、宿主配置都跑通了。最后一步是把模型调用这条线接上让 MCP 工具背后真的能调到大模型。统一用 TaoToken 的 API 地址 https://taotoken.net/api Key 从控制台拿https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。如果你在服务端工具里要调模型可以这样写import os from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlhttps://taotoken.net/api ) def ask_model(prompt: str) - str: resp client.chat.completions.create( model你的模型名, messages[{role: user, content: prompt}] ) return resp.choices[0].message.content把这个函数再用mcp.tool包一层就变成了「模型能力」本身也是一个 MCP 工具宿主可以像调普通函数一样调它。长期跑编码和 Agent 任务的话Coding Plan 的通道更适合持续调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入细节和兼容通道说明都在文档里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。实测下来fastmcp 最省心的地方就是「写函数即工具」配合统一 Key 通道从本地原型到多宿主联调基本不用改结构。唯一要盯紧的是版本MCP 协议还在快速演进生产环境把版本钉死升级前先看迁移指南。