結論先說
- 先分清兩個包:早期 FastMCP 1.0 曾併入官方
mcp包(且官方 SDK v2 已把內置類改名為MCPServer);而現在大家常說的獨立版 FastMCP 是單獨安裝的fastmcp包(官網gofastmcp.com),導入寫from fastmcp import FastMCP。 - 定義一個工具只需
@mcp.tool裝飾器:同步函數和async def異步函數都支持,函數名、類型標註和文檔字符串會自動轉成給模型看的 JSON Schema。 - 參數精細校驗靠
Annotated搭配 PydanticField:像ge=1、le=50、Literal枚舉這類規則既會寫進工具描述提示模型,也會在服務端執行前強制攔截非法輸入。 - 本地測試不一定要起子進程:FastMCP 自帶內存級
Client(mcp),幾行異步腳本就能在本地跑通單測,也可以用fastmcp dev打開網頁調試面板。 - 主力模型訂閱與帳號配套入口:跑通 MCP 工具鏈與多文件智能體編碼依賴穩定的底層大模型配額,國內免境外卡自助開通可見本站 Claude Code 訂閱頁、ChatGPT Plus 充值頁 與 AI 會員充值總覽。

圖:本站根據 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()
這段寫法裏有四個關鍵設計:
@mcp.tool不帶括號也能用:不需要額外元數據時直接寫@mcp.tool;需要聲明只讀或破壞性提示時,像上面這樣傳annotations={"readOnlyHint": True}。- 雙重防線校驗:
min_length=2、ge=1、le=50和Literal會直接編譯進工具的 JSON Schema 字段約束,模型端就能提前避開越界值;萬一模型還是傳錯了,FastMCP 會在進入函數體之前攔截並返回清晰的校驗報錯,讓模型自己改參數重試。 Context自動注入且對模型隱藏:函數簽名裏聲明ctx: Context後,框架會在運行時自動傳入上下文對象(用於打日誌ctx.info或彙報進度ctx.report_progress),並且不會把ctx暴露進工具參數列表裏干擾模型。- stdio 模式同樣不能亂用
print():本機子進程通信佔用標準輸出,業務調試日誌請通過ctx.info()或 Python 標準logging輸出到標準錯誤流。
編程訂閱與高配額省心方案:在 Cursor、Claude Code 或 Codex 裏掛載外部工具做長鏈路開發時,固定月費訂閱通常比純按量 API 更易控成本。本站支持支付寶、微信支付與 AlipayHK 免密自助兌換 Claude Pro、Claude Max 與 ChatGPT Pro,團隊協作亦可定製 ChatGPT Business 團隊版。
三、本地調試的兩種快辦法

圖:本站根據 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,全程無需交出帳號密碼,支持開具增值稅發票;實時價格與售後邊界(封號不在質保範圍)以對應商品頁為準。
相關教學
- MCP Server 開發入門(Python):用官方 SDK 寫第一個 MCP 伺服器並調試
- MCP Inspector 怎麼用:安裝、啟動命令、調試 MCP 伺服器與 v2 的變化
- Claude Code MCP 配置教學:claude mcp add、配置文件位置與常用 MCP
- Cursor MCP 配置教學:mcp.json 寫法、項目與全局位置、OAuth 與連接失敗排查
- MCP 的 stdio、SSE 和 Streamable HTTP 有什麼區別:本地與遠程 MCP 怎麼選
參考資料
- FastMCP 官方文檔站:https://gofastmcp.com
- FastMCP 官方 GitHub 倉庫:https://github.com/jlowin/fastmcp
- MCP 官方 Python SDK 倉庫:https://github.com/modelcontextprotocol/python-sdk
0 條評論
還沒有評論,來搶沙發~