從 0 開發一個 MCP Server：手把手教你構建 AI 工具調用能力

現有 AI 模型「不夠聰明」的根本原因，是缺乏存取外部工具與即時資料的能力。你希望 Claude 查資料庫、GPT 呼叫 API、Cursor 操作檔案系統——這正是 MCP 要解決的問題。工具呼叫能力經歷了 Function Calling → Plugins → MCP 的演進：Function Calling 綁定單一廠商；Plugins 生態封閉；MCP 則提供跨模型、跨客戶端的開放標準。

Anthropic 於 2024 年 11 月設計 MCP，核心目標是標準化 AI 與外部工具的通訊協議，解決 N 個模型 × M 個工具 = N×M 客製化整合的困境。讀完本文，你將能獨立開發並部署一個可上線的 MCP Server。

• 重複造輪子：為 Cursor、Claude Desktop、VS Code 各寫一套檔案系統接入邏輯。
• 換模型即重寫：從 Claude 遷移到 GPT，整合層全部推倒重來。
• 資源與提示詞無標準：Function Calling 只管「呼叫函式」，無法原生暴露唯讀資源與可複用 Prompt 範本。
• 除錯黑箱：工具呼叫失敗時缺乏統一的 Inspector 與 JSON-RPC 日誌。

Client 是 AI 模型端（Claude Desktop、Cursor、自訂客戶端）；Server 是你開發的能力提供方。二者透過 JSON-RPC 2.0 通訊，傳輸方式支援 stdio（本機程序）與 HTTP + SSE（遠端服務）。生命週期為：初始化握手 → 能力協商 → 請求/回應 → 關閉。

Server 暴露三大核心能力：

• Tools：AI 可呼叫的函式（搜尋、計算、資料庫查詢）
• Resources：AI 可讀取的資源（檔案、URL、資料流）
• Prompts：預定義的提示詞範本

Python（推薦新手）：官方 SDK mcp，語法簡潔易上手。TypeScript（推薦前端/全端）：官方 SDK @modelcontextprotocol/sdk。本文以 Python 為主，TypeScript 做對照說明。

# Python
python -m venv .venv
source .venv/bin/activate
pip install mcp

# TypeScript（對照）
npm init -y
npm install @modelcontextprotocol/sdk

建議專案結構：

my-mcp-server/
├── server.py
├── tools/
│   ├── calculator.py
│   └── web_search.py
├── resources/
│   └── file_reader.py
├── prompts/
│   └── templates.py
├── tests/
│   └── test_tools.py
├── pyproject.toml
└── README.md

除錯工具：MCP Inspector（官方除錯 UI）、Claude Desktop 本機聯調、Cursor 的 .cursor/mcp.json 設定。官方文件見 modelcontextprotocol.io。

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-first-server")

@mcp.tool()
def say_hello(name: str) -> str:
    """向指定的人打招呼"""
    return f"Hello, {name}! 這是你的第一個 MCP 工具。"

if __name__ == "__main__":
    mcp.run()

python server.py
npx @modelcontextprotocol/inspector python server.py

在 Cursor 的 .cursor/mcp.json 或 Claude Desktop 的 claude_desktop_config.json 中設定 command + args 指向 python server.py，重啟後驗證工具出現在 AI 上下文中。

工具的基本結構：函式簽名即文件——參數型別、回傳型別、docstring 會被 MCP 轉成 JSON Schema 供模型理解。命名使用 snake_case，錯誤應回傳結構化資訊而非裸例外。

from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(description="搜尋關鍵字")
    max_results: int = Field(default=5, description="最多回傳結果數")
    language: str = Field(default="zh", description="結果語言")

@mcp.tool()
def web_search(input: SearchInput) -> list[dict]:
    """執行網路搜尋，回傳相關結果清單"""
    ...

五個實用工具建議作為練手清單：

• 計算機：數學運算式求值（eval 需沙箱限制）
• 檔案讀寫：讀取/寫入允許目錄內的本機檔案
• HTTP 請求：呼叫外部 REST API
• 資料庫查詢：執行唯讀 SQL
• 時間工具：取得目前時間、時區轉換

import httpx

@mcp.tool()
async def fetch_url(url: str) -> str:
    """取得指定 URL 的內容"""
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
        return response.text

錯誤處理最佳實務：回傳結構化錯誤資訊、設定逾時（建議 30s）、在 Server 層做權限校驗，避免將憑證外洩到客戶端設定。

Resource 與 Tool 的差異：Resource 是資料提供者（唯讀），Tool 是動作執行者。透過 URI 定址：file://、http://、custom://。

@mcp.resource("config://app-settings")
def get_app_settings() -> str:
  return json.dumps({"version": "1.0", "env": "production"})

@mcp.resource("user://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    user = db.query_user(user_id)
    return json.dumps(user)

資源類型涵蓋文字（text/plain、application/json）、二進位（圖片、PDF）與串流資源（即時資料）。檔案系統資源伺服器可實作：列出目錄、讀取檔案、監聽檔案變更（資源訂閱）。

MCP Prompt 是預定義的提示詞片段，支援動態參數注入，提升一致性與可維護性。可定義包含 user 與 assistant 的多輪範本，適用於程式碼審查、面試模擬、除錯助手等場景。

from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def code_review_prompt(language: str, code: str) -> list[PromptMessage]:
    return [
        PromptMessage(
            role="user",
            content=TextContent(
                type="text",
                text=f"請對以下 {language} 程式碼進行審查..."
            )
        )
    ]

mcp = FastMCP("remote-server", transport="streamable-http")

if __name__ == "__main__":
    mcp.run(host="0.0.0.0", port=8000)

生產環境須設定 Bearer Token 驗證、API Key 校驗中介層、CORS 與請求頻率限制。憑證集中在 Server 層管理，而非分散到各客戶端。

可引用資料點 1：截至 2026 年，MCP 生態已有超過 10,000 個 Server。

可引用資料點 2：企業採用 MCP 後，工具整合開發成本降幅約 38–55%（業界調研區間）。

可引用資料點 3：MCP Python SDK 在 PyPI 月下載量已突破 500 萬（2026 Q2）。

使用 MCP Inspector 啟動除錯介面，測試 Tools 呼叫、檢視 JSON-RPC 請求/回應日誌、模擬錯誤情境。單元測試可啟動子程序 Server 並透過 ClientSession 呼叫：

from mcp.client.session import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

async with stdio_client(StdioServerParameters(
    command="python", args=["server.py"]
)) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool("calculate", {"expression": "2 + 2"})
        assert result.content[0].text == "4"

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "server.py"]

部署選項：Railway / Render（個人專案一鍵部署）、AWS Lambda / Google Cloud Run（Serverless）、自建 VPS（配合 Nginx 反向代理）。監控建議：結構化請求日誌、Prometheus 工具呼叫指標、Sentry 錯誤告警、健康檢查介面。版本管理須宣告 MCP 協議版本，採向後相容的工具升級策略。

需求：讓 AI 能搜尋本機 Markdown 筆記、支援語意搜尋（向量檢索）、支援建立與更新筆記。

技術選型：本機向量資料庫 ChromaDB / Qdrant；嵌入模型 text-embedding-3-small；檔案監聽 watchfiles。

• 筆記索引工具：掃描目錄，分塊嵌入寫入向量庫
• 語意搜尋工具：依 query 回傳 Top-K 相關片段
• 筆記寫入工具：建立或追加 Markdown 檔案
• 檔案資源服務：透過 Resource URI 暴露筆記全文

效果演示：在 Cursor 中問「我上週記錄了什麼關於 MCP 的筆記？」——AI 呼叫 MCP 搜尋工具，回傳相關筆記片段。

優質社群 Server：mcp-server-filesystem（檔案系統）、mcp-server-github（GitHub 儲存庫）、mcp-server-brave-search（網路搜尋）、mcp-server-postgres（資料庫）、mcp-server-slack（Slack 訊息）。

2026 趨勢：OpenAI、Google、Microsoft 均已宣布支援 MCP；治理權移交 Linux Foundation AAIF；MCP Marketplace 快速發展；企業級安全標準（OAuth 2.1）進入路線圖。

下一步學習路徑：深入學習 MCP 協議規範；開發並發布公開 MCP Server；探索 MCP + Agent 組合；貢獻開源生態（Python SDK、TypeScript SDK、Inspector）。

1. 01
   確定傳輸模式：本機開發用 stdio；團隊共享或遠端 Claude Code 呼叫用 HTTP+SSE，在 Server 層集中管理 API Key。
2. 02
   控制台撥備雲端 Mac：登入 NUKCLOUD 控制台，選擇 16 GB+ 記憶體（多 Server 並行建議 32 GB）；見 定價頁 按小時試跑。
3. 03
   安裝 Python 3.12 + mcp：SSH 登入後 pip install mcp httpx pydantic；用 MCP Inspector 本機冒煙測試。
4. 04
   部署 HTTP Server 並暴露埠號：mcp.run(host="0.0.0.0", port=8000)；設定 Bearer Token 中介層與 CORS。
5. 05
   客戶端接入驗證：在 Cursor .cursor/mcp.json 指向雲端 URL；確認 tools/list 與 tools/call 冒煙通過。
6. 06
   launchd 常駐與固定月租：撰寫 LaunchAgents plist 保持 7×24 執行；試點通過後於 下單頁 鎖定規格。詳見 NUKCLOUD 生產就緒 Runbook。

在本機筆電或共用 VPS 跑 HTTP MCP Server 常見合蓋休眠中斷工作階段、頻寬抖動導致 SSE 斷連、多開發者搶占同一程序。需要穩定長連線供 Cursor Background Agents 或個人知識庫 Server 7×24 服務時，NUKCLOUD 多區域裸金屬 Mac / 雲端 Mac 節點在獨佔租戶邊界與規格彈性上更易與 MCP 工作流對齊。