第三方工具更新 2026.11.22

MCP Python SDK 教學:Windows 建立工具,接上 Codex 與 Claude Code

用 MCP Python SDK 2.3.0 在 Windows 建立報價工具,接上 Codex 與 Claude Code。包含可複製 Python 程式、整數金額與 ToolError 錯誤回傳。

MCP Python SDK 能把你的 Python 函式提供給 AI 客戶端呼叫。已經有明確的計算或查詢規則、希望 AI 使用同一套邏輯時很適合;只是請 AI 寫 Python,或現有工具已經夠用,就不必再建伺服器。

下面用官方 SDK 2.3.0 做一個報價工具:AI 提供單價、數量與折扣,Python 計算金額,並把不合理輸入的原因回傳給 AI。重點是從客戶端真的呼叫成功,而不只是在 Python 裡載入函式。

安裝 SDK 與啟動 CLI

需要 uv 和 Codex CLI 或 Claude Code。在新的專案資料夾開 PowerShell:

uv venv --python 3.12 .venv
uv pip install --python .venv\Scripts\python.exe "mcp[cli]==2.3.0"
$mcpCli = (Resolve-Path .venv\Scripts\mcp.exe).Path
$server = Join-Path (Get-Location).Path server.py

[cli] 會安裝 mcp run 所需的命令列工具。本文使用 2.x 的 MCPServer,和舊版 SDK 內的 FastMCP 匯入方式不同;也不是獨立的 fastmcp 套件。

建立一個有輸入檢查的報價工具

把以下內容存為專案的 server.py。金額以整數「分」傳遞,讓小數捨入規則保持明確:

from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError
from mcp.types import ToolAnnotations

mcp = MCPServer("Order quote")

@mcp.tool(annotations=ToolAnnotations(
    read_only_hint=True, destructive_hint=False,
    idempotent_hint=True, open_world_hint=False,
))
def quote_order(unit_price_cents: int, quantity: int, discount_percent: int = 0) -> dict[str, int]:
    """Calculate a quote in integer cents; discount must divide the gross amount exactly."""
    if unit_price_cents < 0:
        raise ToolError("unit_price_cents must be non-negative")
    if quantity < 1:
        raise ToolError("quantity must be at least 1")
    if not 0 <= discount_percent <= 100:
        raise ToolError("discount_percent must be between 0 and 100")
    gross = unit_price_cents * quantity
    if gross * discount_percent % 100:
        raise ToolError("discount produces a fractional cent; choose an explicit rounding rule")
    discount = gross * discount_percent // 100
    return {"gross_cents": gross, "discount_cents": discount, "net_cents": gross - discount}

型別註記描述參數與回傳資料;函式內的檢查負責數量、折扣範圍和金額規則。ToolError 用來把可預期、適合讓使用者看到的錯誤原因傳回客戶端。

這份模組由 mcp run 載入,沒有在檔案底部自行啟動伺服器,也不會把除錯文字印到 stdio 的協定輸出。

接上 AI 工具

Codex CLI

在同一個 PowerShell 視窗執行:

codex mcp add mcp-python-sdk -- $mcpCli run $server --transport stdio
codex mcp list

清單會列出這個伺服器與完整命令。重新開啟 Codex 對話,指定使用 quote_order,再核對實際工具呼叫與結果。

Claude Code

claude mcp add mcp-python-sdk --scope project --transport stdio -- $mcpCli run $server --transport stdio
claude mcp list

健康檢查應顯示 ✓ Connected。客戶端會啟動 stdio 子程序,不需要另外開 HTTP port。

Cursor 設定請參考 官方 MCP 文件,server 的啟動方式見 SDK 文件。

三個實際用途

1. 讓 AI 使用既定公式算金額

用 quote_order,unit_price_cents=12000、quantity=2、discount_percent=0。
回報工具回傳的 gross_cents、discount_cents、net_cents,不要自己心算替代呼叫。

實際結果是原價 24000 分、折扣 0 分、應付 24000 分。這條路徑可以讓不同對話共用同一個計算規則。

2. 比較折扣前後的報價

用同一個 quote_order,單價12000分、數量2、discount_percent=10。
與零折扣的工具結果比較,說明減少幾分。不要修改伺服器或檔案。

回傳 gross_cents=24000、discount_cents=2400、net_cents=21600。輸出欄位把原價和折扣分開,比只回傳一句總價更容易核對。

3. 確認 AI 能看懂拒絕輸入的原因

先呼叫 quote_order,單價12000分、數量0、折扣0;保留實際錯誤。
再呼叫單價1分、數量1、折扣10,檢查工具如何處理不足一分的折扣。
不要替工具補寫沒有回傳的原因。

兩次都被拒絕。第一個結果含 quantity must be at least 1;第二個含 discount produces a fractional cent; choose an explicit rounding rule。工具把規則說清楚,AI 才有依據修正輸入。

常見錯誤與解法

客戶端只看到 Error executing tool quote_order

我們第一版用 ValueError,客戶端確實只收到這句一般錯誤,沒有數量或金額原因。改用上面範例的 ToolError 後,才收到完整說明。把可公開的業務錯誤與內部例外分開,避免把內部細節全部傳給客戶端。

quantity must be at least 1

這是函式裡的業務規則,不是 MCP 沒連上。傳入至少 1 的數量;若你的業務允許數量 0,應先修改規則與測試,再讓客戶端使用。

discount produces a fractional cent

這個範例會拒絕無法用整數分表示的折扣。單價 1 分再打九折就是其中一例。正式應用需要先決定四捨五入、無條件捨去或其他規則,再實作,不能默默把餘數丟掉。

限制、費用與選擇

這是確定性計算示範,沒有商品庫存、付款或訂單寫入。工具註記描述它唯讀、無外部存取;註記本身不會限制任意 Python 程式的權限。新增檔案或服務存取時,仍要設計對應的權限與輸入檢查。

SDK 採 MIT 授權,本身不提供模型,也不另外收模型 API 費。AI 客戶端與模型用量分開計算。本文只接 stdio;HTTP 的啟動、驗證與部署請看官方文件。

如果已有 FastAPI 端點,可評估 FastAPI adapter;若偏好更多應用層功能,參考 FastMCP。要檢查工具 schema 與錯誤,可看 MCP Inspector。

FAQ

MCP Python SDK 和 FastMCP 一樣嗎?

官方 SDK 與獨立 FastMCP 是不同套件。本文固定 mcp[cli]==2.3.0,使用 MCPServer。看舊教學時,先核對套件名稱、版本與 import,再複製程式碼。

建立 MCP 工具需要模型 API key 嗎?

這個本機伺服器只執行 Python 函式,不需要模型 key。接上 Codex 或 Claude Code 後,由客戶端提供模型並決定何時呼叫。若你的函式本身要連外部服務,才會另有該服務的設定。

為什麼只宣告函式,沒有 mcp.run()?

本文用 mcp run server.py --transport stdio 載入名為 mcp 的伺服器物件,再啟動傳輸。僅執行或匯入定義檔,並不等於已建立客戶端連線。不要同時加另一個啟動入口而讓載入流程互相干擾。

為什麼要實測錯誤輸入?

正常數字算對,只能證明正常路徑。數量 0、折扣範圍和不足一分的金額,都需要明確處理。這次測試也因此發現一般例外沒有把原因傳給 AI,改成 ToolError 後才補上這個資訊。

官方參考

我們測了什麼

2026-11-16,Windows、Python 3.12、mcp[cli] 2.3.0、Codex CLI 0.169.0。 Codex 真的呼叫兩種報價與兩種錯誤輸入;比較 ValueError 與 ToolError 的回傳差異;Claude Code add/list 顯示 Connected。 未測 Cursor、HTTP、遠端部署、外部資料庫與付款流程。

訂閱 AI 工具精選與使用建議

有值得推薦的新工具、實測發現或重要更新時,寄到你的信箱。

訂閱後先寄給你一份每月更新的 AI 工具與 Skill 清單。有值得推薦的工具、實測發現或重要更新時才寄信,隨時可以退訂。隱私權說明

快完成了,請到信箱收確認信點信裡的按鈕確認訂閱,就會收到工具清單的下載連結。沒看到的話,看一下垃圾郵件或「促銷內容」分頁。

看過去幾期

也可以在這些平台追蹤: