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、遠端部署、外部資料庫與付款流程。