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

工具調用能力經歷了三代演進：Function Calling（廠商私有格式）→ Plugins（平台綁定）→ MCP（開放協議標準）。Anthropic 設計 MCP 的核心動機，是用一套 JSON-RPC 規範統一「AI 客戶端如何發現、描述並調用外部能力」，終結 N 個模型 × M 個工具的自訂整合噩夢。

• 痛點切入：模型缺乏存取外部工具與即時資料的能力，無法查庫、調 API、操作檔案。
• 場景描述：你希望 Claude / GPT 能查資料庫、調 REST API、讀寫本地 Markdown——這正是 MCP Server 要暴露的能力。
• 價值承諾：讀完本文，你能獨立開發並部署一個生產可用的 MCP Server。

架構上，MCP Client（Claude Desktop、Cursor 等）與 MCP Server（你開發的部分）透過 JSON-RPC 雙向通信，Server 再對接外部系統：

• Tools：AI 可調用的函式（搜尋、計算、資料庫查詢）
• Resources：AI 可讀取的資源（檔案、URL、資料流）
• Prompts：預定義的提示詞模板，支援參數注入

通信基於 JSON-RPC 2.0，傳輸方式分兩種：stdio（本地子進程，延遲極低）與 HTTP + SSE / Streamable HTTP（遠端服務，支援多客戶端）。生命週期為：初始化握手 → 能力協商 → 請求/回應 → 關閉。

延伸閱讀：MCP 為何成為 AI 時代的 HTTP 協議；官方規範見 modelcontextprotocol.io。

Python（推薦新手）：官方 SDK mcp，FastMCP 裝飾器簡潔易上手。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/
│   ├── __init__.py
│   ├── calculator.py
│   └── web_search.py
├── resources/
│   └── file_reader.py
├── prompts/
│   └── templates.py
├── tests/
│   └── test_tools.py
├── pyproject.toml
└── README.md

除錯工具三件套：

• MCP Inspector：官方除錯 UI，可視化測試 Tools / Resources / Prompts
• Claude Desktop：編輯 claude_desktop_config.json 做本地聯調
• Cursor MCP 配置：Settings → MCP → 添加 stdio 命令列啟動項

用 FastMCP 十行程式碼即可跑通第一個 Server：

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
# 或使用 MCP Inspector 除錯
npx @modelcontextprotocol/inspector python server.py

Cursor 接入六步：

1. 確認 Python 路徑：虛擬環境中 which python 記下絕對路徑。
2. 開啟 Cursor MCP 設定：Settings → Features → MCP Servers。
3. 添加 stdio Server：command 填 Python 路徑，args 填 server.py 絕對路徑。
4. 重啟 Cursor：使 MCP 配置生效。
5. 驗證工具列表：在 Agent 模式查看是否出現 say_hello。
6. 觸發調用：對話中讓 AI「用 say_hello 向 JEXCLOUD 打招呼」，確認回傳正確。

Claude Desktop 同理：編輯 ~/Library/Application Support/Claude/claude_desktop_config.json，在 mcpServers 節點註冊同名配置。

工具的基本契約：函式簽名即文件——參數類型、回傳類型、docstring 會被 MCP 轉為 JSON Schema 供 AI 理解。命名用 snake_case，錯誤優先回傳結構化資訊而非裸異常。

複雜參數用 Pydantic 建模：

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]:
    """執行網路搜尋，回傳相關結果列表"""
    ...

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

• 計算器：安全求值數學表達式（ast.literal_eval 防注入）
• 檔案讀寫：限定白名單目錄內的 read / write
• HTTP 請求：封裝 GET / POST，統一逾時與重試
• 資料庫查詢：唯讀 SQL + 參數化防注入
• 時間工具：目前時間、時區轉換、ISO 8601 格式化

IO 密集型工具用非同步：

import httpx

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

錯誤處理最佳實踐：設定逾時、權限校驗（路徑白名單 / API Key）、回傳 {"error": "...", "code": "..."} 結構體便於 AI 自我修正。

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（Base64 或 blob URI）
• 串流：即時日誌、行情推送（資源訂閱）

檔案系統資源伺服器實戰：列出目錄 → 按路徑讀取檔案 → 可選 watchfiles 監聽變更並推送資源更新通知。

MCP Prompt 是預定義的提示詞片段，AI 客戶端可直接複用，支援動態參數注入，提升團隊提示詞的一致性與可維護性。

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} 程式碼進行審查..."
            )
        )
    ]

多輪對話模板可混合 user 與 assistant 角色，典型場景：面試模擬（先 assistant 提問、再 user 作答）、程式碼除錯助手（assistant 引導排障步驟）。

from mcp.server.fastmcp import FastMCP

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

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

生產環境須疊加：Bearer Token 認證、API Key 中介軟體、CORS 白名單、請求頻率限制（如 slowapi）。遠端 Server 適合團隊共享資料庫查詢、內部 API 閘道等能力。

MCP Inspector 工作流：啟動 Inspector → 連接 stdio 命令 → 在 UI 中測試 tools/call → 查看 JSON-RPC 請求/回應日誌 → 模擬逾時與權限拒絕場景。

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

@pytest.mark.asyncio
async def test_calculator_tool():
    server_params = StdioServerParameters(command="python", args=["server.py"])
    async with stdio_client(server_params) 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 反向代理 + TLS，配合 Bearer Token

可觀測性三件套：結構化請求日誌、Prometheus 工具調用指標、Sentry 錯誤告警；暴露 /health 健康檢查。版本管理須宣告 MCP 協議版本，工具升級保持向後相容，利用能力協商避免客戶端崩潰。

• MCP Python SDK：github.com/modelcontextprotocol/python-sdk
• MCP TypeScript SDK：github.com/modelcontextprotocol/typescript-sdk
• MCP Inspector：github.com/modelcontextprotocol/inspector

需求：讓 AI 能搜尋本地 Markdown 筆記、語意檢索、建立與更新筆記。

技術選型：

• 向量資料庫：ChromaDB 或 Qdrant（本地輕量）
• 嵌入模型：text-embedding-3-small（OpenAI）或本地 nomic-embed-text
• 檔案監聽：watchfiles 增量重建索引

核心模組：

• index_notes 工具：掃描筆記目錄，切塊嵌入寫入向量庫
• semantic_search 工具：query → top-k 相關片段
• write_note 工具：建立 / 追加 Markdown 檔案
• notes://{path} 資源：按 URI 讀取單篇筆記全文

效果演示：在 Cursor 中問「我上週記錄了什麼關於 MCP 的筆記？」→ AI 調用 semantic_search → 回傳相關片段並綜合回答。這是把私有知識接入 Agent 工作流的最短路徑。

優質社群 Server 推薦：

• mcp-server-filesystem：檔案系統操作
• mcp-server-github：GitHub 倉庫操作
• mcp-server-brave-search：網路搜尋
• mcp-server-postgres：資料庫查詢
• mcp-server-slack：Slack 訊息

2026 生態趨勢：Cursor、Claude Desktop、VS Code、OpenAI、Google Gemini 均已原生或計劃支援 MCP；MCP Marketplace 加速 Server 分發；企業級安全標準（OAuth 2.1、審計日誌）進入路線圖。

下一步學習路徑：精讀 MCP 協議規範 → 發布第一個公開 Server → 探索 MCP + Agent 編排 → 向開源生態貢獻 PR。

• 協議版本：2024-11-05 首發，2025 起 Streamable HTTP 替代純 SSE 成為遠端傳輸推薦方案
• 生態規模：截至 2026 年，社群 MCP Server 已超過 10,000 個
• SDK 維護方：Anthropic 開源 + Linux Foundation AAIF 治理，Python / TypeScript 雙官方 SDK 週更

MCP 是 AI 工具化的標準協議——掌握 Server 開發，等於掌握了讓任意 LLM 調用你業務系統的能力。你打算用 MCP 封裝什麼工具？歡迎在評論區分享場景。

生產級 MCP Server 的隱性成本在宿主穩定性：筆電合蓋 STDIO 子進程即死、家用頻寬抖動打斷 HTTP 長連線、共享 VPS 無 macOS 沙箱與 TCC 權限。若你需要 7×24 運行知識庫索引、遠端 HTTP MCP 或配合 Cursor Agent 做 CI，JEXCLOUD 多區域裸機 Mac 提供獨占 Apple Silicon、固定公網 IP、120 秒交付與按月彈性租期——比「本地湊合 + 頻繁重連」更適合生產 Agent 工作流。節點與價格見 JEXCLOUD 定價頁，部署問題見 幫助中心。