如何建立一個最簡單的 MCP 伺服器？

依 MCP 官方教學，用 Python SDK 只要安裝 mcp 套件、建立 MCPServer 物件、以 @mcp.tool() 裝飾一個函式，再用 stdio 模式執行，就完成一個可被 Claude Desktop 等客戶端呼叫的 MCP 伺服器。

需要準備什麼？

• Python 3.10 以上
• Python MCP SDK 2.0.0 以上（官方教學要求）
• 套件管理工具 uv
• 要測試時需安裝最新版 Claude Desktop

步驟

1. 安裝 uv

   官方教學使用 uv 管理 Python 專案與套件，安裝後請重新開啟終端機。

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. 建立專案並安裝 MCP SDK

   建立專案資料夾與虛擬環境，再安裝含命令列工具的 mcp 套件。

   uv init demo
   cd demo
   uv venv
   source .venv/bin/activate
   uv add "mcp[cli]"

3. 撰寫伺服器程式

   建立 server.py，用 MCPServer 建立伺服器，並以 @mcp.tool() 註冊工具。SDK 會依型別提示與 docstring 自動產生工具說明。

   from mcp.server import MCPServer
   
   mcp = MCPServer("demo")
   
   
   @mcp.tool()
   async def add(a: int, b: int) -> int:
       """把兩個整數相加。
   
       Args:
           a: 第一個整數
           b: 第二個整數
       """
       return a + b
   
   
   if __name__ == "__main__":
       mcp.run(transport="stdio")

4. 啟動伺服器

   執行後伺服器會透過標準輸入輸出（stdio）等待 MCP 客戶端連線，終端機沒有畫面是正常的。

   uv run server.py

5. 接到 Claude Desktop 測試

   在 claude_desktop_config.json 的 mcpServers 中加入這個伺服器，路徑必須是絕對路徑，存檔後完全結束並重新開啟 Claude Desktop。

   {
     "mcpServers": {
       "demo": {
         "command": "uv",
         "args": ["--directory", "/ABSOLUTE/PATH/TO/demo", "run", "server.py"]
       }
     }
   }

常見錯誤

• stdio 模式下不能用 print() 輸出到標準輸出，會破壞 JSON-RPC 訊息；請改用 logging 模組（寫到 stderr）
• 設定檔中的專案路徑用了相對路徑，導致 Claude Desktop 找不到程式
• Claude Desktop 找不到 uv 指令時，需在 command 填入 uv 的完整路徑（macOS／Linux 用 which uv 查詢）
• 參考舊教學寫 from mcp.server.fastmcp import FastMCP；目前官方教學以 SDK 2.0 的 MCPServer 為準

常見問題

MCP 伺服器一定要用 Python 寫嗎？

不用。官方教學同時提供 TypeScript、Java、Kotlin、C# 等版本，例如 TypeScript 版使用 @modelcontextprotocol/server 套件與 McpServer 類別，概念相同。

MCP 伺服器除了工具還能提供什麼？

MCP 伺服器可提供三種能力：工具（Tools，讓模型呼叫的函式）、資源（Resources，可讀取的檔案或資料）與提示範本（Prompts），入門通常先從工具開始。

相關名詞

模型上下文協議、函式呼叫／工具使用、AI 代理人

參考來源

• Model Context Protocol：Build an MCP server
• GitHub：modelcontextprotocol/python-sdk

查核日期：2026-09-26。API：/api/howto?id=build-mcp-server