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 條評論

登入 後參與評論

還沒有評論,來搶沙發~