Python FastMCP 建立 MCP Server 完整教學：讓 AI 助手呼叫你的自訂工具

如果你最近有在關注 AI 開發生態圈，應該會發現一個詞不斷出現——MCP。全名 Model Context Protocol，它正在快速成為 AI 助手連接外部工具的標準協議。而 FastMCP 這個 Python 套件，讓建立 MCP Server 變得簡單到有點不真實。

我自己在三個月前開始用 FastMCP，從一開始的小工具到現在公司內部有十幾個 MCP Server 在跑，這篇文章把我踩過的坑和最佳實踐一次整理給你。

MCP 是什麼

簡單來說，MCP（Model Context Protocol）是 Anthropic 在 2024 年底提出的開放協議，目的是讓 AI 模型能夠透過標準化的方式來呼叫外部工具、讀取資料來源、執行動作。你可以把它想成是「AI 界的 USB」——定義好插頭的規格，任何裝置都能連上去。

在 MCP 出現之前，每個 AI 平台都有自己的 function calling 格式。OpenAI 用 JSON Schema 定義 functions，Google 用 Vertex AI 的 Tool，各家都不一樣。MCP 統一了這些定義方式，讓你寫一次工具就能被所有支援 MCP 的 AI 助手使用。

截至 2026 年初，支援 MCP 的平台包括：Claude Desktop、Claude Code、ChatGPT（透過插件）、Cursor、Windsurf、以及大量的第三方 AI 應用。據統計，目前全球有超過 70% 的 MCP Server 是用 FastMCP 建的——這個數字還在持續增長。

MCP 的三個核心概念

• Tools：AI 可以呼叫的函式，例如查詢天氣、操作資料庫、發送訊息
• Resources：AI 可以讀取的資料來源，例如文件內容、設定檔、API 回應
• Prompts：預先定義好的提示模板，讓使用者可以快速觸發常見工作流程

FastMCP 安裝與設定

安裝非常簡單。我推薦用 Python Ruff 來管理程式碼品質，然後用 uv 或 pip 來裝 FastMCP：

pip install fastmcp

或者如果你跟我一樣在用 uv：

uv add fastmcp

安裝完之後，建立一個最基本的 MCP Server 只需要四行程式碼：

from fastmcp import FastMCP

mcp = FastMCP("My Server")

@mcp.tool()
def hello(name: str) -> str:
    """跟使用者打招呼"""
    return f"你好，{name}！"

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

就這樣。執行 python server.py 之後，你就有一個運作中的 MCP Server 了。FastMCP 會自動處理所有的協議細節——JSON-RPC 通訊、參數驗證、錯誤處理，全部幫你搞定。

第一個 MCP Tool

讓我們來做一個更實用的例子。假設你想建立一個能查詢公司內部知識庫的 MCP Tool：

from fastmcp import FastMCP
import httpx

mcp = FastMCP("Knowledge Base")

@mcp.tool()
async def search_docs(query: str, limit: int = 5) -> str:
    """搜尋公司內部知識庫
    
    Args:
        query: 搜尋關鍵字
        limit: 回傳結果數量上限
    """
    async with httpx.AsyncClient() as client:
        resp = await client.get(
            "https://api.internal.com/search",
            params={"q": query, "limit": limit}
        )
        results = resp.json()
    
    formatted = []
    for doc in results["items"]:
        formatted.append(f"## {doc['title']}
{doc['summary']}")
    
    return "

".join(formatted)

這裡有幾個重點值得注意。首先，FastMCP 完全支援 async/await，所以你可以直接用非同步的 HTTP client。其次，函式的 docstring 非常重要——AI 模型會讀這段文字來判斷什麼時候該呼叫這個工具。寫得越清楚，AI 的判斷就越準確。

型別標註（type hints）也很關鍵。FastMCP 會根據你定義的型別自動產生 JSON Schema，讓 AI 知道每個參數應該傳什麼格式的值。如果你想更精確地控制參數驗證，可以搭配 Pydantic 的 Field 使用：

from pydantic import Field

@mcp.tool()
def calculate_price(
    base_price: float = Field(description="原始價格", gt=0),
    discount: float = Field(description="折扣百分比", ge=0, le=100)
) -> str:
    """計算折扣後的價格"""
    final = base_price * (1 - discount / 100)
    return f"折扣後價格：${final:.2f}"

如果你之前有用過 FastAPI 建立 API，你會發現 FastMCP 的設計理念非常相似。這不是巧合——FastMCP 的作者就是受到 FastAPI 啟發而開發的。

Resource 與 Prompt

除了 Tool 之外，MCP 還定義了 Resource 和 Prompt 兩個概念。

Resource 代表 AI 可以讀取的資料來源。跟 Tool 不同的是，Resource 通常是被動的——AI 會在需要背景資訊的時候去讀取它，而不是主動執行某個動作。

@mcp.resource("config://app")
def get_app_config() -> str:
    """取得應用程式設定"""
    config = load_config()
    return json.dumps(config, indent=2)

@mcp.resource("file://{path}")
def read_file(path: str) -> str:
    """讀取指定路徑的檔案內容"""
    with open(path, "r") as f:
        return f.read()

Prompt 則是預定義的提示模板，讓使用者在 AI 介面中可以快速選擇常見的工作流程：

@mcp.prompt()
def code_review(code: str, language: str = "python") -> str:
    """產生程式碼審查的提示"""
    return f"請審查以下 {language} 程式碼，指出潛在問題並提供改進建議：

```{language}
{code}
```"

我個人的經驗是，大多數場景用 Tool 就夠了。Resource 在需要提供大量背景資料的時候特別好用（例如讓 AI 讀取整個設定檔或文件），而 Prompt 則適合團隊內部共享常用的 AI 工作流程。

部署到生產環境

開發階段用 mcp.run() 跑 stdio 模式就好，但生產環境我推薦用 SSE（Server-Sent Events）模式：

if __name__ == "__main__":
    mcp.run(transport="sse", host="0.0.0.0", port=8000)

這樣你的 MCP Server 就會以 HTTP 服務的方式運作，可以部署到任何支援 Python 的雲端平台。我自己是部署在 Railway 上，每月成本大概是 5 美金，處理幾千次呼叫完全沒問題。

如果你的工具需要呼叫其他 API 或資料庫，記得把敏感資訊放在環境變數裡：

import os

DB_URL = os.environ["DATABASE_URL"]
API_KEY = os.environ["API_KEY"]

另外一個常見的部署方式是透過 Docker。FastMCP 官方有提供 Dockerfile 範例，基本上就是標準的 Python Docker 映像加上你的程式碼。如果你對 Web 框架部署比較熟悉，也可以參考 FastHTML 的部署方式，概念是類似的。

連接到 Claude Desktop

要讓 Claude Desktop 使用你的 MCP Server，需要編輯設定檔 claude_desktop_config.json：

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["path/to/server.py"]
    }
  }
}

重啟 Claude Desktop 之後，你的工具就會出現在聊天介面中。每次 Claude 判斷需要使用你的工具時，會自動呼叫對應的 function 並把結果帶回對話裡。

常見問題

FastMCP 跟直接用 MCP SDK 有什麼差別？

MCP SDK 是底層的協議實作，你需要自己處理很多細節。FastMCP 是高階的包裝層，用裝飾器的方式讓你專注在商業邏輯上。關係就像 ASGI 跟 FastAPI 的關係。

一個 MCP Server 可以有幾個 Tool？

技術上沒有限制，但實務上建議不要超過 20 個。太多工具會讓 AI 模型難以判斷該用哪一個，反而降低準確度。如果你有很多工具，建議拆成多個 MCP Server。

FastMCP 支援串流回應嗎？

目前 MCP 協議本身不支援 Tool 的串流回應，但 Resource 可以。FastMCP 會在未來版本中支援更多串流場景。如果你需要處理大量資料的回傳，建議先把資料存起來，然後回傳一個存取連結。

安全性怎麼處理？

MCP Server 本質上就是一個被 AI 呼叫的 API，所以標準的 API 安全實踐都適用：驗證輸入、限制權限、加密傳輸。FastMCP 內建了基本的輸入驗證（透過型別標註和 Pydantic），但你還是應該在工具內部做額外的權限檢查。

MCP 生態圈還在快速發展中，但核心概念已經穩定了。如果你是 Python 開發者，現在就是開始建立 MCP Server 的最好時機——學習曲線很平緩，而且未來的應用場景只會越來越多。