FastMCP MCP — 使用場景, 安裝 & 即時演示

為什麼要用

核心特性

每個工具只需一個裝飾器：@mcp.tool 或 @mcp.resource
型別提示自動轉換為 JSON schema，無需手動撰寫
以非同步為優先，同時支援同步——標準函式庫的型別標註皆可運作
內建傳輸方式：stdio（供桌面客戶端使用）、SSE / 可串流 HTTP（供遠端使用）

即時演示

實際使用效果

fastmcp.replay ▶ 就緒

0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示，然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "fastmcp": {
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "fastmcp",
      "command": "uvx",
      "args": [
        "fastmcp"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列，而非映射。

~/.config/zed/settings.json

{
  "context_servers": {
    "fastmcp": {
      "command": {
        "path": "uvx",
        "args": [
          "fastmcp"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add fastmcp -- uvx fastmcp

一行命令搞定。用 claude mcp list 驗證，claude mcp remove 移除。

使用場景

實戰用法： FastMCP

在一小時內將內部 REST API 封裝為 MCP

👤 擁有現有 Python 服務的後端工程師 ⏱ ~45 min intermediate

何時使用： 你有一個公司 API 需要讓 Agent 呼叫，但不想從頭撰寫客戶端規格。

前置條件

Python 3.10+ — python --version
uv installed — curl -LsSf https://astral.sh/uv/install.sh | sh

步驟

初始化專案

建立一個名為 'acme-api-mcp' 的 FastMCP 伺服器專案，包含一個範例工具。使用 uv 管理相依套件。✓ 已複製

→ 生成 pyproject.toml 與 server.py，其中包含可運作的 @mcp.tool 範例
封裝價值最高的 3 個端點

我的內部 API 有 /orders/{id}、/customers/search、/invoices/{id}/pdf 這三個端點。請分別用 FastMCP 為每個端點撰寫工具，使用 httpx.AsyncClient，並從環境變數讀取 AUTH_TOKEN。✓ 已複製

→ 3 個帶有型別提示與 docstring 的裝飾函式，docstring 即成為工具描述
使用 MCP Inspector 在本地測試

執行 uv run mcp dev server.py 啟動伺服器，打開 Inspector 並以實際的輸入測試每個工具。✓ 已複製

→ 工具回傳預期的 JSON，無 stack trace

結果： 一個可運作的 MCP 伺服器，可直接連接 Claude Desktop 或任何 MCP 客戶端。

注意事項

因在 docstring 中輸出機密資訊，導致憑證外洩至工具描述中 — docstring 應描述行為，而非含有真實 token 的範例。透過 os.environ 載入機密，且絕不在錯誤訊息中輸出它們
混用非同步與同步程式碼，導致 event loop 錯誤 — 選擇其中一種——若 HTTP 客戶端是非同步的，則整個工具都應為非同步；不要在工具內呼叫 asyncio.run

將公司文件封裝為 MCP 資源以支援 RAG

👤 建構 Agent 基礎設施的平台工程師 ⏱ ~30 min intermediate

何時使用： 你希望 Agent 能自動探索並取得公司知識庫，而不需要對每個檔案都進行工具呼叫。

步驟

定義資源列表

定義一個 URI 為 docs://{path} 的 FastMCP 資源，列出 ./docs/ 目錄下所有 Markdown 檔案，並在讀取時回傳其內容。✓ 已複製

→ 資源已註冊，Inspector 顯示列表
新增範本資源

新增一個資源範本 docs://{category}/{slug}，回傳對應的檔案。並說明有效的 {category} 值。✓ 已複製

→ 範本已註冊，參數化的資源取得可正常運作
在真實客戶端中測試

將 Claude Desktop 連接至伺服器，確認資源選單列出所有文件，且內容可正常載入。✓ 已複製

→ 資源以可附加的上下文形式出現

結果： 一個由資源支撐的知識介面，Agent 可直接從中取得資料——比針對靜態內容進行工具呼叫更為簡潔。

注意事項

資源列表過大，造成客戶端 UI 無法負荷 — 在列表端點加入分頁或篩選機制，不必將所有檔案都對外呈現

將 FastMCP 伺服器部署為遠端 SSE 端點

👤 為多個團隊提供服務的平台工程師 ⏱ ~60 min advanced

何時使用： 多位開發者需要使用相同的 MCP——只需部署一次，不必讓每個人在本地執行 stdio。

前置條件

A container host (Cloud Run, Fly, Railway) — Any Docker-capable runtime works

步驟

切換傳輸方式為 SSE

修改 server.py，改為執行 mcp.run(transport='sse', host='0.0.0.0', port=8080)，並新增一個最精簡的 Dockerfile。✓ 已複製

→ 在本地執行 curl localhost:8080/sse 可看到 SSE 握手回應
部署並加上驗證保護

使用 IAM 驗證部署至 Cloud Run，並在 FastAPI 中介層中為 /sse 端點加入基於標頭的驗證檢查。✓ 已複製

→ 公開 URL 對未驗證的請求回傳 401
設定客戶端連線

將連線指令分享給團隊成員：npx -y mcp-remote https://mcp.acme.com/sse。確認他們的 Claude Desktop 能正確載入工具。✓ 已複製

→ 團隊成員的客戶端看到相同的工具清單

結果： 一個共用的遠端 MCP——單一程式碼庫，多人使用，易於更新。

注意事項

SSE 連線在某些企業代理伺服器後方會斷線 — 改用 streamable HTTP 傳輸（較新的規格），或說明需要 VPN / 直連的要求

搭配使用： cloud-run

組合

與其他 MCP 搭配，撬動十倍槓桿

fastmcp + cloud-run

一次建構，部署至 Cloud Run，與團隊共用

將我的內部定價 API 封裝為 FastMCP 伺服器，容器化後部署至 Cloud Run 並啟用 IAM 驗證。✓ 已複製

fastmcp + fastapi-mcp

比較兩種方案——全新專案用 FastMCP，現有 FastAPI 應用程式用 fastapi-mcp

我有一個現有的 FastAPI 服務，該為它加上 fastapi-mcp 來公開路由，還是重寫成 FastMCP？請根據我的路由進行比較。✓ 已複製

工具

此 MCP 暴露的能力

工具	輸入參數	何時呼叫	成本
@mcp.tool	decorated function with typed signature	將任何你想讓 Agent 呼叫的函式封裝起來	free
@mcp.resource	URI template + function	公開可讀取的內容（文件、設定、資料快照）	free
@mcp.prompt	decorated function returning Message[]	向客戶端提供可重複使用的多輪對話提示鷹架	free
mcp.run	transport: 'stdio'\|'sse'\|'streamable-http', host?, port?	進入點——在主程式腳本末尾呼叫	free
Context (ctx) parameter	inject ctx: Context into any tool	需要串流進度回報或記錄日誌的長時間執行工具	free

成本與限制

運行它的成本

API 配額: 無——這是一個框架，而非服務
每次呼叫 Token 數: 你的伺服器執行任何 LLM 呼叫；框架本身的開銷可忽略不計
費用: 免費，開源
提示: 靜態內容請使用資源而非工具——資源在 token 消耗上更節省，因為它們是預先宣告的

安全

權限、密鑰、影響範圍

憑證儲存： 由你決定——環境變數是慣用方式；在程序啟動時載入機密，而非每次呼叫時載入

資料出站： 取決於你的工具函式對外呼叫的目標位置

故障排查

常見錯誤與修復

Tool schema missing required fields in the client

函式參數需要型別提示。單純的 def foo(x) 只會產生無用的 schema——請改用 def foo(x: str) 並附上 docstring。

驗證： Run `uv run mcp dev server.py` and check the Inspector's tool schema

Server starts but client sees 0 tools

你混淆了 stdio 與 SSE 的設定。Claude Desktop 請使用 transport='stdio'；mcp-remote 請使用 'sse'。

`ImportError: No module named 'fastmcp'`

請執行 uv pip install fastmcp 安裝，或將其加入 pyproject.toml 的相依套件中。確認你是在相同的 venv 環境中執行伺服器。

驗證： uv pip show fastmcp

Async tool hangs on first call

你在非同步工具中引入了同步的 httpx。請使用帶有 async with 的 httpx.AsyncClient——切勿混用。

替代方案

FastMCP 對比其他方案

替代方案	何時用它替代	權衡
TypeScript MCP SDK	你的團隊使用 TS/Node 且希望保持一致的技術選型	官方維護、品質穩定、開發體驗相近——只是語言不同
fastapi-mcp	你已有 FastAPI 應用程式，想將路由公開為工具	對 MCP 介面的控制度較低，但現有服務無需重構即可使用
csharp-sdk	.NET 技術棧	第一方支援，但範例生態系統相對較小

FastMCP

為什麼要用

核心特性

即時演示

實際使用效果

安裝

選擇你的客戶端

使用場景

實戰用法： FastMCP

前置條件

步驟

注意事項

步驟

注意事項

前置條件

步驟

注意事項

組合

與其他 MCP 搭配，撬動十倍槓桿

工具

此 MCP 暴露的能力

成本與限制

運行它的成本

安全

權限、密鑰、影響範圍

故障排查

常見錯誤與修復

替代方案

FastMCP 對比其他方案

更多

資源