/ 目錄 / 演練場 / MCP Python SDK
● 官方 modelcontextprotocol ⚡ 即開即用

MCP Python SDK

作者 modelcontextprotocol · modelcontextprotocol/python-sdk

Model Context Protocol 的官方 Python SDK——用 30 行程式碼建構伺服器和客戶端,附帶 FastMCP 相容的裝飾器。

Anthropic 官方維護的 MCP Python SDK。提供伺服器(mcp.server.fastmcp.FastMCP)、客戶端(mcp.client.session.ClientSession)和更底層的基本元件。被用作規格合規性的標準參考——有疑問時,這是唯一的權威來源。基於裝飾器的 FastMCP API 已從 jlowin/fastmcp 合併而來。

為什麼要用

核心特性

即時演示

實際使用效果

mcp-python-sdk.replay ▶ 就緒
0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "mcp-python-sdk": {
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ],
      "_inferred": true
    }
  }
}

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

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "mcp-python-sdk": {
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ],
      "_inferred": true
    }
  }
}

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

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "mcp-python-sdk": {
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ],
      "_inferred": true
    }
  }
}

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

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "mcp-python-sdk": {
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ],
      "_inferred": true
    }
  }
}

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

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "mcp-python-sdk",
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ]
    }
  ]
}

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

~/.config/zed/settings.json
{
  "context_servers": {
    "mcp-python-sdk": {
      "command": {
        "path": "uvx",
        "args": [
          "--with",
          "mcp",
          "python",
          "-m",
          "mcp.server.example"
        ]
      }
    }
  }
}

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

claude mcp add mcp-python-sdk -- uvx --with mcp python -m mcp.server.example

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

使用場景

實戰用法: MCP Python SDK

在 10 分鐘內用 Python 建構你的第一個 MCP 伺服器

👤 MCP 新手的 Python 開發者 ⏱ ~15 min beginner

何時使用: 你想將一個 Python 函式暴露給 Claude。

前置條件
  • Python 3.10+ — uv 或 pyenv
步驟
  1. 安裝並建立框架
    Use uv to install mcp. Create server.py with one tool: get_weather(city) that calls a public API.✓ 已複製
    → 帶有 @tool 裝飾器的 10 行檔案
  2. 透過 stdio 執行
    Run mcp dev server.py. Open the MCP Inspector and verify the tool listing.✓ 已複製
    → 工具可從 inspector 呼叫
  3. 新增到 Claude Desktop
    Add to claude_desktop_config.json. Test from Claude.✓ 已複製
    → 對話中的即時回應

結果: 在 Claude 中注冊的 Python MCP 伺服器正常工作。

注意事項
  • 在處理器中使用 print() 導致 stdio 損壞 — 使用 logging 輸出到 stderr;絕不寫入 stdout

使用 SDK 的客戶端為 MCP 伺服器撰寫整合測試

👤 將 MCP 發布到正式環境的開發者 ⏱ ~30 min intermediate

何時使用: 你需要能證明 MCP 行為正確的 CI 測試。

步驟
  1. 啟動伺服器
    Use mcp.client.stdio to spawn server.py and call list_tools(). Assert expected names.✓ 已複製
    → 測試通過
  2. 呼叫每個工具
    For each tool, call with a representative input and assert the output schema.✓ 已複製
    → 所有工具已驗證
  3. 連接到 pytest
    Convert into pytest fixtures so CI runs them on every PR.✓ 已複製
    → 可重用的測試框架

結果: 有信心工具不會退化的 MCP 伺服器。

在工具執行期間將長時間執行的輸出即時串流回 Claude

👤 為建置、部署或長時間模擬建構 MCP 的開發者 ⏱ ~45 min advanced

何時使用: 工具需要數分鐘,你想要在對話中看到進度,而非等完成後。

步驟
  1. 使用 streamable HTTP 傳輸
    Switch from stdio to streamable HTTP. Yield progress events from the tool.✓ 已複製
    → Claude 在執行期間顯示部分輸出
  2. 新增取消功能
    Honor cancel requests so user can abort if the tool takes too long.✓ 已複製
    → 取消在執行中途有效

結果: 即使很慢也讓工具感覺即時。

組合

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

mcp-python-sdk + mcp-go-mark3labs

多語言——效能關鍵用 Go,ML/資料用 Python

mcp-python-sdk + mcp-registry

將你的 Python MCP 發布到官方注冊表

工具

此 MCP 暴露的能力

工具輸入參數何時呼叫成本
FastMCP name, version? 頂層伺服器建立 0
@server.tool decorator on async function 每個你想暴露的函式 0
@server.resource decorator with uri pattern 唯讀資料暴露 0
@server.prompt decorator on prompt builder 可重用的提示模板 0
ClientSession transport 測試或建構 MCP 客戶端 0
stdio_server () 本地模式 0

成本與限制

運行它的成本

API 配額
不適用——函式庫
每次呼叫 Token 數
不適用
費用
免費(MIT)
提示
在 pyproject.toml 中固定 SDK 版本;規格仍在演進

安全

權限、密鑰、影響範圍

憑證儲存: 取決於你的工具需要什麼
資料出站: 由你的處理器控制

故障排查

常見錯誤與修復

工具未出現

確認 @tool 裝飾器在非同步函式上,且函式在伺服器啟動前已注冊

驗證: 執行 `mcp dev server.py` 並開啟 inspector
Pydantic 驗證錯誤

工具輸入由 Pydantic 驗證;檢查型別提示是否與 Claude 傳送的內容相符

伺服器在 stdin EOF 時掛起

確認你的非同步處理器不會死鎖——使用 anyio 以確保相容性

替代方案

MCP Python SDK 對比其他方案

替代方案何時用它替代權衡
FastMCP (PrefectHQ)你想要帶有額外工具的原始第三方分支現在大多已合併回來;是薄薄的封裝層
mcp-go (mark3labs)Go 是你的語言不同的生態系統

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

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