MCP Server 開發入門（Python）：用官方 SDK 寫第一個 MCP 伺服器並調試

本文根據 MCP 官方 Python SDK 倉庫的 README、文檔首頁和《Migration Guide》整理，資料核對於 2026-10-11。MCP 是什麼見《MCP 是什麼》。文中代碼取自官方 README，沒有在本機運行驗證。

適用於誰

• 搜「mcp server 開發」「mcp server 開發 python」「mcp server 開發教學」「fastmcp 教學」的人；
• 已經會給 Claude Code、Cursor 配別人的 MCP 伺服器，想把公司內部的接口或腳本也接進來的人；
• 照着舊教學寫 from mcp.server.fastmcp import FastMCP，升級後發現對不上的人。

結論先說

1. 官方 Python SDK 的包名是 mcp，安裝時帶上 cli 附加項：pip install "mcp[cli]"，需要 Python 3.10 及以上。
2. 十幾行代碼就是一個伺服器：創建一個 MCPServer 實例，用 @mcp.tool() 裝飾函數就是工具，用 @mcp.resource(...) 就是資源。函數的類型標註和文檔字符串會成為給模型看的參數定義和說明。
3. 調試用 mcp dev server.py，它會啟動伺服器並打開 MCP Inspector。
4. v2 改了類名：FastMCP 已改名為 MCPServer，導入路徑也變了。裝飾器的用法和 v1 相同。
5. stdio 伺服器絕不能往標準輸出打印東西，日誌要寫到標準錯誤。這是協議規定，也是新手最常見的故障原因。

一、三個基本概念

一個 MCP 伺服器可以向客戶端提供三類東西：

入門階段只需要工具。

二、安裝

官方給出兩種方式：

bash
uv add "mcp[cli]"

bash
pip install "mcp[cli]"

cli 附加項提供 mcp 命令行；不需要命令行時裝普通的 mcp 即可。

另外，調試用的 Inspector 是一個 Node.js 程序，官方文檔提醒需要 npx 在你的 PATH 裏，也就是要先裝好 Node.js。

三、寫第一個伺服器

新建 server.py，下面是官方 README 的快速上手示例：

python
from mcp.server import MCPServer

mcp = MCPServer("Demo")


@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b


@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

逐行看：

• MCPServer("Demo")：創建伺服器，Demo 是它的名稱；
• @mcp.tool()：把下面的函數註冊為工具。a: int, b: int 這些類型標註決定了工具的參數定義，三引號裏的文檔字符串是給模型看的工具說明；
• @mcp.resource("greeting://{name}")：註冊一個帶模板的資源，{name} 會作為參數傳給函數。

工具說明要寫給模型看。模型只憑名稱和說明決定何時調用、怎麼填參數，「Add two numbers.」這種一句話對簡單工具夠用；實際業務裏的工具要寫清它做什麼、參數的含義和取值範圍。

四、調試

bash
uv run mcp dev server.py

這條命令啟動伺服器並打開 MCP Inspector，一個在瀏覽器裏運行的調試介面。打開終端裏打印出來的地址，官方文檔給的驗證步驟是：

• 在 Tools 裏調用 add，填 a=1、b=2，應當得到 3；
• 在 Resources 裏讀取 greeting://World，應當得到 Hello, World!。

先在 Inspector 裏把工具調通，再接進真正的客戶端。這樣出問題時能分清是伺服器的問題還是客戶端配置的問題。Inspector 的詳細用法見《MCP Inspector 怎麼用》。

五、兩種運行方式

MCP 定義了兩種標準傳輸方式，區別見《MCP 的 stdio、SSE 和 Streamable HTTP 有什麼區別》。簡單說：

• stdio：客戶端把你的伺服器當作子進程啟動，通過標準輸入輸出通信。本機自用的伺服器用這種；
• Streamable HTTP：伺服器作為獨立的 HTTP 服務運行，客戶端通過網址連接。要給多人用、或部署在別的機器上時用這種。

用 Streamable HTTP 運行的官方命令：

bash
uv run mcp run server.py --transport streamable-http

官方 README 接着給了一個客戶端示例，用來驗證伺服器可以被調用：

python
import asyncio

from mcp import Client


async def main() -> None:
    async with Client("http://localhost:8000/mcp") as client:
        result = await client.call_tool("add", {"a": 1, "b": 2})
        print(result.structured_content)  # {'result': 3}


asyncio.run(main())

官方說明：給 Client 傳一個網址就表示用 Streamable HTTP；它也可以啟動本地的 stdio 子進程。

六、接進客戶端

• Claude Code：遠程服務用 claude mcp add --transport http，本地 stdio 服務把啟動命令放在 -- 後面，寫法見《Claude Code MCP 配置教學》；
• Claude 桌面版：在 claude_desktop_config.json 的 mcpServers 裏加一項，見《Claude Desktop MCP 配置》；
• Cursor、Codex、Trae：見《Cursor MCP 配置教學》、《Codex 怎麼配置 MCP》、《Trae 規則與 MCP 配置教學》。

SDK 的命令行還有一個 mcp install 子命令，具體用法以官方文檔為準。

七、從 v1 升級：FastMCP 改名了

網上大量教學是按 v1 寫的。官方《Migration Guide》裏和入門相關的幾條：

遷移指南列了全部不兼容的改動，升級已有項目前通讀一遍。v1.x 的文檔官方另行保留。

八、寫伺服器時的幾條規矩

1. stdio 伺服器不要 print。 協議規定：伺服器不得向標準輸出寫入任何不是合法 MCP 消息的內容；日誌可以寫到標準錯誤。在工具函數里隨手 print() 一句調試資訊，就會破壞通信，表現為客戶端連不上或者莫名斷開。

2. 工具要小而明確。 一個工具做一件事，參數用明確的類型；可選值有限時用枚舉，而不是讓模型自由填字符串。

3. 報錯訊息寫給模型看。 工具失敗時返回「哪裏不對、期望什麼」，模型才能自己修正後重試。

4. 密鑰走環境變量。 不要寫進代碼，客戶端配置裏用各自的 env 傳入。

5. HTTP 服務要考慮安全。 協議對 Streamable HTTP 的要求包括：校驗 Origin 請求頭、本地服務綁定到 127.0.0.1 而不是所有網卡、為連接實現鑑權。要對外提供服務時，這三條都要落實。

常見問題

Q：必須用 uv 嗎？

不是。官方同時給了 pip install 的寫法；文檔裏的命令以 uv run 開頭，是因為它用 uv 管理項目環境。用 pip 時在已激活的虛擬環境裏直接運行 mcp dev server.py。

Q：FastMCP 還能用嗎？

官方 SDK 的 v2 裏這個類已改名為 MCPServer。繼續用 v1 的寫法就要把依賴固定在 v1.x 版本。

Q：用 TypeScript 可以嗎？

可以，MCP 官方也有 TypeScript 等語言的 SDK，本文沒有覆蓋。

Q：客戶端裏看不到我的工具？

先用 Inspector 確認伺服器本身正常；再看客戶端的日誌。stdio 伺服器重點查兩件事：啟動命令和路徑是否是絕對路徑、代碼裏有沒有往標準輸出打印內容。

參考資料

• MCP Python SDK（官方倉庫）：https://github.com/modelcontextprotocol/python-sdk
• SDK 文檔首頁：https://github.com/modelcontextprotocol/python-sdk/blob/main/docs/index.md
• Migration Guide（v1 → v2）：https://github.com/modelcontextprotocol/python-sdk/blob/main/docs/migration.md
• mcp（PyPI）：https://pypi.org/project/mcp/
• Transports（MCP 規範）：https://modelcontextprotocol.io/specification/2025-11-25/basic/transports