/ 目錄 / 演練場 / FastAPI MCP
← 全部伺服器 ↗ GitHub
● 社群 tadata-org ⚡ 即開即用

FastAPI MCP

作者 tadata-org · tadata-org/fastapi_mcp

掛載一行程式碼，將每個 FastAPI 路由變成 MCP 工具——結構描述來自你的 Pydantic 模型，驗證來自你的中介層。

fastapi-mcp 封裝現有的 FastAPI 應用程式，並將其路由以 MCP 工具的形式公開。工具的結構描述由你的 Pydantic 請求／回應模型自動產生，現有的驗證中介層維持不變運作。這是從「我有一個 Python API」到「代理程式可以呼叫它」的最快途徑。

▶ 觀看演示 📦 安裝 💡 使用場景

為什麼要用

核心特性

即時演示

實際使用效果

fastapi-mcp.replay ▶ 就緒
0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "fastapi-mcp": {
      "command": "uvx",
      "args": [
        "fastapi-mcp"
      ]
    }
  }
}

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

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "fastapi-mcp": {
      "command": "uvx",
      "args": [
        "fastapi-mcp"
      ]
    }
  }
}

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

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "fastapi-mcp": {
      "command": "uvx",
      "args": [
        "fastapi-mcp"
      ]
    }
  }
}

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

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "fastapi-mcp": {
      "command": "uvx",
      "args": [
        "fastapi-mcp"
      ]
    }
  }
}

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

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "fastapi-mcp",
      "command": "uvx",
      "args": [
        "fastapi-mcp"
      ]
    }
  ]
}

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

~/.config/zed/settings.json
{
  "context_servers": {
    "fastapi-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "fastapi-mcp"
        ]
      }
    }
  }
}

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

claude mcp add fastapi-mcp -- uvx fastapi-mcp

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

使用場景

實戰用法： FastAPI MCP

無需重構，將現有 FastAPI 應用程式以 MCP 形式公開

👤 擁有運行中 FastAPI 服務的後端開發者 ⏱ ~30 min intermediate

何時使用： 你已經有一個 FastAPI API 在運行，想讓代理程式使用它，同時不想維護兩份平行的程式碼庫。

前置條件
  • 運作中的 FastAPI 應用程式，且請求／回應有 Pydantic 模型 — 若你的路由回傳 dict，請先重構為 Pydantic BaseModel — 否則工具結構描述將會是 object
步驟
  1. 安裝並掛載
    將 fastapi-mcp 加入我的專案。在我的 main.py 中，於 app = FastAPI() 之後加上 FastApiMCP(app).mount()。顯示差異。✓ 已複製
    → 差異極小；伺服器仍可正常運行
  2. 確認工具出現
    啟動伺服器。使用 npx -y mcp-remote http://localhost:8000/mcp 連線。列出工具——我所有的 GET/POST 路由都有出現嗎？✓ 已複製
    → 工具已列出，名稱與路由的 operation_id 相符
  3. 篩選公開的路由
    我不想公開 /admin/* 路由。使用 include_operations 或依標籤排除來重新設定。✓ 已複製
    → 管理路由不再出現於工具清單中

結果： 你現有的 API 現在可透過 MCP 存取，且不需重複任何結構描述或邏輯。

注意事項
  • 每個路由都會成為工具——包含你不打算公開的內部路由 — 正式上線前明確設定 include_tags=['public'] 或 exclude_operations=[...]
  • 沒有 operation_id 的路由會產生像 read_item_items__item_id__get 這樣難看的名稱 — 路由上永遠明確設定 operation_id：@app.get('/items/{id}', operation_id='get_item')
搭配使用： fastmcp

將有驗證的 FastAPI 應用程式以 MCP 形式公開，且不破壞驗證機制

👤 在 FastAPI 上使用 bearer／OAuth2 的後端開發者 ⏱ ~30 min intermediate

何時使用： 你的 FastAPI 路由使用 Depends(get_current_user) — 你需要透過 MCP 呼叫時仍然觸發驗證。

前置條件
  • 現有的驗證依賴注入 — Depends(oauth2_scheme) 或同等方式
步驟
  1. 將 Authorization 標頭透傳
    設定 fastapi-mcp，將 MCP 上下文中的 Authorization 標頭轉發給底層路由。指出相關設定位置。✓ 已複製
    → 設定變更後，路由現在可以收到標頭
  2. 測試需驗證的呼叫
    透過 MCP 呼叫受保護的端點。先不帶 token（預期 401），再帶有效 token（預期 200）。✓ 已複製
    → 401 未授權、200 已授權——與直接 HTTP 呼叫相同
  3. 撰寫用戶端設定文件
    撰寫使用者所需的 mcp-remote 設定，讓他們的 Claude Desktop 能傳送 Authorization 標頭。✓ 已複製
    → 可直接複製貼上的用戶端設定片段

結果： 無論從 curl 或代理程式呼叫，驗證機制均以相同方式強制執行。

注意事項
  • 代理程式不小心使用長效的根權限 token — 為每位使用者簽發短效的有限範圍 token；積極輪換——將 MCP 視為任何其他 API 用戶端對待

將 MCP 端點與現有 API 一起部署

👤 平台工程師 ⏱ ~45 min advanced

何時使用： 你在 Cloud Run／Fly／Render 上運行 FastAPI，想讓 MCP 共用同一份部署。

步驟
  1. 掛載於固定路徑
    將 fastapi-mcp 掛載於 /mcp。確認 /docs（Swagger）與 /mcp 都能從同一個程序運作。✓ 已複製
    → 兩個路徑均有回應
  2. 透過現有入口公開
    更新我的 Cloud Run／nginx／API gateway 設定，將 /mcp 路由到此服務，並設定 SSE 相容的逾時（不緩衝、允許長時間閒置）。✓ 已複製
    → 遠端 mcp-remote 可順利連線
  3. 撰寫用戶端設定文件
    撰寫給團隊的 README：如何將此 MCP 加入 Claude Desktop + Cursor。✓ 已複製
    → 每個用戶端各有可複製貼上的設定

結果： 一份部署、兩種協定（REST + MCP），不需額外基礎設施。

注意事項
  • 代理伺服器緩衝 SSE 回應，導致連線看起來卡住 — 停用代理緩衝——nginx：proxy_buffering off；Cloud Run：預設已無此問題；Cloudflare：啟用串流
搭配使用： cloud-run · vercel

組合

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

fastapi-mcp + fastmcp

在同一個程序中，用 fastapi-mcp 處理舊有路由，用 FastMCP 建立全新的代理程式專屬工具

為我現有的 /api/* 路由掛載 fastapi-mcp，並為代理程式專屬操作（如 bulk_sync）新增 3 個 FastMCP 工具。✓ 已複製
fastapi-mcp + cloud-run

在 Cloud Run 上將 REST 與 MCP 一起部署

取得我的 FastAPI 服務，加入 fastapi-mcp，容器化，並部署至 Cloud Run，在 /mcp 上設定 IAM 驗證。✓ 已複製

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
FastApiMCP(app, **options) app: FastAPI, include_operations?, exclude_operations?, include_tags?, exclude_tags?, name?, description? 建置時進行接線——在啟動時建立一次 free
.mount(path='/mcp') path? 緊接於實例化之後呼叫 free
Auto-generated tools derived from each FastAPI route's request/response models 無需任何操作——掛載後自動出現 same as your route

成本與限制

運行它的成本

API 配額
繼承自你的 API
每次呼叫 Token 數
與直接 HTTP 呼叫相同——無額外負擔
費用
免費，開放原始碼
提示
將冗長的管理／除錯路由排除於 MCP 之外——它們會污染代理程式的工具清單，並在每次 list_tools 時消耗 token

安全

權限、密鑰、影響範圍

憑證儲存： 依你的 FastAPI 所使用的方式——fastapi-mcp 不會新增額外的驗證層
資料出站： 與你的路由原本流向相同的地方

故障排查

常見錯誤與修復

Tools appear but calls return 422 validation errors

你的路由使用 dict 而非 Pydantic BaseModel——MCP 傳入具型別的 JSON，但你的路由無法解析。請重構為 BaseModel。

Route exists at /items but no matching tool

在某些情況下，fastapi-mcp 會略過沒有 response_model 或 operation_id 的路由。請加上 response_model=ItemOut 和 operation_id='get_item'。

驗證： curl http://localhost:8000/openapi.json | jq '.paths'
Auth dependency doesn't fire when called via MCP

在 FastApiMCP 選項中設定標頭轉發。若你的依賴注入讀取的是 cookie 而非標頭，請改為基於標頭的驗證——MCP 沒有 cookie jar。

SSE hangs behind nginx

在 /mcp location 區塊加上 proxy_buffering off; proxy_cache off; proxy_read_timeout 3600s;。

替代方案

FastAPI MCP 對比其他方案

替代方案何時用它替代權衡
FastMCP全新開發——沒有現有 FastAPI 應用程式，純粹撰寫 MCP 伺服器新專案開發體驗更佳；改造舊有應用程式則 fastapi-mcp 勝出
Hand-written SDK server需要對工具名稱、描述和結構描述進行精細控制程式碼更多、維護負擔更重——通常不值得

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills