FastMCP(Python)快速写 MCP Server 教程:装饰器定义工具、参数类型校验与本地调试

用独立版 FastMCP 框架(pip install fastmcp)写 Python MCP 服务器:先分清它与官方 mcp 包的区别,再掌握 @mcp.tool 装饰器、Annotated + Pydantic Field 参数校验、内存单测与本地调试。

NNathaniel bigo··原创首发·AI 辅助撰写
12 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 免费账号 账号

结论先说

  1. 先分清两个包:早期 FastMCP 1.0 曾并入官方 mcp 包(且官方 SDK v2 已把内置类改名为 MCPServer);而现在大家常说的独立版 FastMCP 是单独安装的 fastmcp 包(官网 gofastmcp.com),导入写 from fastmcp import FastMCP。
  2. 定义一个工具只需 @mcp.tool 装饰器:同步函数和 async def 异步函数都支持,函数名、类型标注和文档字符串会自动转成给模型看的 JSON Schema。
  3. 参数精细校验靠 Annotated 搭配 Pydantic Field:像 ge=1、le=50、Literal 枚举这类规则既会写进工具描述提示模型,也会在服务端执行前强制拦截非法输入。
  4. 本地测试不一定要起子进程:FastMCP 自带内存级 Client(mcp),几行异步脚本就能在本地跑通单测,也可以用 fastmcp dev 打开网页调试面板。
  5. 主力模型订阅与账号配套入口:跑通 MCP 工具链与多文件智能体编码依赖稳定的底层大模型配额,国内免境外卡自助开通可见本站 Claude Code 订阅页、ChatGPT Plus 充值页 与 AI 会员充值总览。

独立版 FastMCP 与官方 mcp 包区别

图:本站根据 FastMCP 官方文档 与 MCP Python SDK 整理的对比示意图

本文根据 FastMCP 官方文档站(gofastmcp.com)、官方仓库《jlowin/fastmcp》与 MCP 官方《python-sdk》说明整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 FastMCP 或 Anthropic 官方网站。

适用于谁

  • 搜「fastmcp 教程」,想用最少样板代码把 Python 函数封装成 MCP 工具的开发者;
  • 分不清 from fastmcp import FastMCP 和 from mcp.server.fastmcp import FastMCP 为什么写法不一样的读者;
  • 需要严格限制大模型传参范围(比如数值上下限、枚举项、字符串长度)的后端工程师。

一、先避坑:独立 fastmcp 与官方 mcp 包别混导

Python 生态里有两条路都能写 MCP 服务器,网上教程经常把它们混在一起讲,导致新手一运行就报导入错误:

  • 路线 A(本文讲的独立框架):安装 fastmcp 包,由原作者团队在 jlowin/fastmcp 持续迭代,在基础协议之上扩展了服务端组合挂载、OpenAPI / FastAPI 自动转换、内存直连客户端等能力。
  • 路线 B(官方基础 SDK):安装 mcp 包,适合只需要标准协议原语的项目,它的完整入门与 v2 迁移细节见本站 MCP Server 开发入门(Python)。

选定独立版 FastMCP 后,在虚拟环境里直接用 uv 或 pip 安装(要求 Python 3.10 及以上):

bash
uv add fastmcp
# 或者使用 pip:
pip install fastmcp

二、装饰器定义工具与 Pydantic 参数校验

新建 server.py。在实际业务里,光写 limit: int 往往不够,模型可能会传 -5 或 99999 把下游接口拖垮。FastMCP 原生集成 Pydantic 校验,推荐把 typing.Annotated、Literal 和 pydantic.Field 组合起来写:

python
from typing import Annotated, Literal
from pydantic import Field
from fastmcp import FastMCP, Context

mcp = FastMCP("TicketService")


@mcp.tool(annotations={"readOnlyHint": True})
async def search_tickets(
    keyword: Annotated[
        str,
        Field(description="搜索关键词,至少 2 个字符", min_length=2, max_length=50),
    ],
    status: Annotated[
        Literal["open", "pending", "closed"],
        Field(description="工单状态筛选,只能填 open、pending 或 closed"),
    ] = "open",
    limit: Annotated[
        int,
        Field(description="返回条数上限,范围 1 到 50", ge=1, le=50),
    ] = 10,
    ctx: Context | None = None,
) -> list[dict]:
    """按关键词和状态检索内部客服工单列表。"""
    if ctx:
        await ctx.info(f"正在检索关键词:{keyword},状态:{status}")
    return [{"id": 101, "title": f"示例工单:{keyword}", "status": status}][:limit]


if __name__ == "__main__":
    mcp.run()

这段写法里有四个关键设计:

  1. @mcp.tool 不带括号也能用:不需要额外元数据时直接写 @mcp.tool;需要声明只读或破坏性提示时,像上面这样传 annotations={"readOnlyHint": True}。
  2. 双重防线校验:min_length=2、ge=1、le=50 和 Literal 会直接编译进工具的 JSON Schema 字段约束,模型端就能提前避开越界值;万一模型还是传错了,FastMCP 会在进入函数体之前拦截并返回清晰的校验报错,让模型自己改参数重试。
  3. Context 自动注入且对模型隐藏:函数签名里声明 ctx: Context 后,框架会在运行时自动传入上下文对象(用于打日志 ctx.info 或汇报进度 ctx.report_progress),并且不会把 ctx 暴露进工具参数列表里干扰模型。
  4. stdio 模式同样不能乱用 print():本机子进程通信占用标准输出,业务调试日志请通过 ctx.info() 或 Python 标准 logging 输出到标准错误流。
编程订阅与高配额省心方案:在 Cursor、Claude Code 或 Codex 里挂载外部工具做长链路开发时,固定月费订阅通常比纯按量 API 更易控成本。本站支持支付宝、微信支付与 AlipayHK 免密自助兑换 Claude Pro、Claude Max 与 ChatGPT Pro,团队协作亦可定制 ChatGPT Business 团队版。

三、本地调试的两种快办法

用 FastMCP 开发与调试四步流程

图:本站根据 FastMCP 官方文档 整理的开发调试流程示意图

写完服务端代码后,先别急着去重启桌面软件,推荐按下面两步在本地验通:

1. 用内存客户端写 10 行脚本测逻辑

独立版 FastMCP 的一大省事之处,是可以把 mcp 实例直接塞给同包的 Client,在内存里完成协议层调用,连端口和子进程都不用起:

python
import asyncio
from fastmcp import Client
from server import mcp


async def test_local():
    async with Client(mcp) as client:
        tools = await client.list_tools()
        print("已注册工具数:", len(tools))
        res = await client.call_tool("search_tickets", {"keyword": "退款", "limit": 5})
        print("调用结果:", res)


asyncio.run(test_local())

2. 用 CLI 打开可视化面板或切 HTTP 运行

想在浏览器界面里点选测试 Schema 渲染效果(本机需装有 Node.js 提供 npx),运行:

bash
fastmcp dev server.py

面板的具体操作方法见 MCP Inspector 怎么用。确认无误后,本机运行默认走 stdio;如果要部署成远程服务给团队共用,指定 HTTP 传输与端口即可(协议选型见 MCP 的 stdio、SSE 和 Streamable HTTP 有什么区别):

bash
fastmcp run server.py --transport http --port 8000

四、挂载到 Claude Code 与 Cursor

本地走 stdio 接入时,建议使用 uv run 指定项目环境启动,避免系统全局 Python 缺包:

  • 接入 Claude Code:在终端执行 claude mcp add ticket-service -- uv run --with fastmcp fastmcp run /绝对路径/server.py。如果你日常经常要基于现有 FastAPI 或内部数据库快速生成并调试这类工具脚本,搭配 Claude Code 在终端里自动跑测试修参数非常顺手,详细命令见 Claude Code MCP 配置教程。
  • 接入 Cursor:在 .cursor/mcp.json 里把对应命令和参数数组填进 mcpServers,配置位置与排错见 Cursor MCP 配置教程。

常见问题

问:已有一个现成的 FastAPI 项目,必须每个接口重新手写一遍 @mcp.tool 吗?

答:不用。独立版 FastMCP 提供了 FastMCP.from_fastapi(app) 与 FastMCP.from_openapi(...) 方法,可以直接把已有路由和 Pydantic 请求体转换成 MCP 工具;不过建议只筛选核心接口暴露,避免一次性生成几十个工具塞满模型上下文。

问:工具函数返回字典或 Pydantic 模型对象可以吗?

答:可以。FastMCP 会自动把字典、列表、Pydantic 模型序列化成协议要求的文本和结构化内容返回给客户端,不需要手动拼嵌套响应结构。

问:报 ModuleNotFoundError: No module named 'fastmcp' 但我明明装过了怎么办?

答:九成是因为你在虚拟环境装了包,但客户端启动时调的是系统默认 python。在客户端配置里把 command 写成虚拟环境内 python(或 fastmcp)可执行文件的绝对路径,或者用 uv run --directory /项目绝对路径 启动即可。

问:配置好开发环境后,国内没有外币卡怎么开通 Claude 或 ChatGPT 编程订阅?

答:可在 本站充值中心 自助选购卡密开通 Claude Code(Pro / Max) 或 ChatGPT Plus / Pro,全程无需交出账号密码,支持开具增值税发票;实时价格与售后边界(封号不在质保范围)以对应商品页为准。

相关教程

参考资料

  • FastMCP 官方文档站:https://gofastmcp.com
  • FastMCP 官方 GitHub 仓库:https://github.com/jlowin/fastmcp
  • MCP 官方 Python SDK 仓库:https://github.com/modelcontextprotocol/python-sdk

Nathaniel 的更多内容

  1. 01

    独立开发者用 ChatGPT + Codex 跑通产品全流程:市场验证、PRD、原型到代码上线复盘清单

    单人做独立产品最容易陷入「闭门写两个月代码上线零用户」或「AI 写到一半目录越改越崩」。本文整理「ChatGPT 负责市场验证、PRD 与复盘 + Codex 负责工程实现与测试」的五阶段双轨流程,附起手提示词与 7 项上线复盘清单。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成规范文件命名规则、整理混乱目录树与合并零散发票抬头清单脚本

    面对满桌面的「新建文件夹」「最终版2」和上百张零散电子发票,手工改名抄台账耗时又容易漏重。本文分享先脱敏取样、再用 ChatGPT 生成带预演和回滚日志的本地 Python 脚本,离线安全完成目录整理与发票抬头合并去重的实战流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外邮件营销(EDM)受众分层文案、A/B 主题行测试与防进垃圾箱自检

    做海外独立站或出海 SaaS 邮件营销(EDM),最怕千人一面群发被直接送进垃圾箱。本文结合 Gmail/Yahoo 批量发件人规范,梳理用 ChatGPT 设计受众分层文案、批量生成 A/B 主题行矩阵并开展发前垃圾词与合规自检的实战提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写 Notion Formula 2.0 公式、Obsidian Dataview 查询与 Airtable 自动化脚本

    给 Notion 数据库写多条件 Formula 2.0 公式、给 Obsidian 写 Dataview 动态看板,或在 Airtable 里写自动化脚本,经常因为一个小括号或类型不匹配报错半天。本文整理三大工具的通用上下文喂料规范与三套直接可复制的生成提示词。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 处理复杂 JSON / YAML / XML 字段映射、格式转换与校验规则编写实战

    对接第三方 API、迁移 Kubernetes 配置或解析政企 XML 报文时,手工对照几百行嵌套字段既慢又容易漏掉空值与类型边界。本文整理用 ChatGPT 完成字段映射表梳理、生成确定性转换脚本以及编写 JSON Schema / Pydantic / XSD 校验规则的实战流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 准备本科/硕士毕业论文答辩:提炼答辩 PPT 结构、模拟导师犀利追问与 3 分钟自述稿

    毕业论文写完后,要在 3–5 分钟内讲清研究价值并顶住答辩评委的连环追问并不轻松。本文整理在严格遵守高校学术规范的前提下,用 ChatGPT 提炼答辩 PPT 结构、打磨 3 分钟口语自述稿并开展模拟导师犀利追问的排练流程与提示词。

    ChatGPT0

同产品的其他教程

  1. 01

    用 ChatGPT 速读英文产品手册、开源文档与 GitHub Issue 并沉淀团队中文内训手册

    团队引入海外 SaaS 工具或开源框架时,全英文文档晦涩冗长、真正的坑全藏在几十页 GitHub Issue 讨论里。本文分享速读拆解英文手册、归类 Issue 排障库以及重构团队中文内训 SOP 的完整实战流程。

    ChatGPT其他 AI 工具0
  2. 02

    用 ChatGPT 写油猴脚本(Tampermonkey)与浏览器书签小工具解决网页繁琐重复操作实战

    每天在后台系统里重复勾选几十个复选框、手工复制网页表格或清理遮挡阅读的侧边栏,既枯燥又浪费时间。本文分享不会写 JS 也能用 F12 配合 ChatGPT 写出油猴脚本与书签小工具的完整实战流程。

    ChatGPT其他 AI 工具0
  3. 03

    用 ChatGPT 写高质量 SQL 窗口函数(RANK / LAG / SUM OVER)做留存与漏斗分析实战

    做用户留存率、复购间隔与有序转化漏斗时,多层自连接既难读又拖垮数据库,窗口函数则是高效解法。本文整理数据库方言喂数规范、CTE 分层提示词以及用内置沙盒先验证再上线的完整实战流程。

    ChatGPT其他 AI 工具0
  4. 04

    ChatGPT 连接 Canva、Figma、Linear、Jira、Dropbox 等第三方应用搜不到数据或授权失效怎么办

    在 ChatGPT 接入 Canva、Figma、Linear、Jira 或 Dropbox 后,明明显示已连接却搜不到文件工单,或老提示授权失效怎么办?本文拆解账号错绑、OAuth 范围漏选、权限继承与管理员拦截 5 步排障法。

    ChatGPT其他 AI 工具0
  5. 05

    Anthropic Contextual Retrieval(上下文增强检索)是什么、怎么实现:给文档块自动补背景摘要结合缓存降失误率

    长文档切成小块后丢了公司名、年份和主语指代导致 RAG 频频搜错?本文按 Anthropic 官方技术文章详解 Contextual Retrieval 原理、官方公开评测失误率下降 49% 至 67% 的组合架构,以及用 Claude 提示词缓存低成本批量生成切片背景的完整 Python 代码。

    Claude其他 AI 工具0
  6. 06

    RAG 知识库回答不准怎么调优:切片大小(Chunking)、BM25 + 向量混合检索与 Rerank 重排序三步排查法

    搭好的 RAG 企业知识库一问具体型号、报错码或跨行表格就答非所问?本文按 OpenAI 与 Anthropic 官方检索文档,给出先隔离检索与生成故障、再按结构化切片(Chunking)、BM25 加向量混合召回(RRF)与 Rerank 重排序逐层调优的三步法。

    Claude其他 AI 工具0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~