從 0 開發 MCP Server 完全指南

大語言模型再強，也無法直接查你的資料庫、讀本機檔案或呼叫內部 API——AI 缺的不是推理能力，而是連接真實世界的手腳。你希望 Claude、GPT 或 Cursor 裡的 Agent 能搜尋筆記、執行 SQL、觸發 Webhook，這正是 MCP（Model Context Protocol，模型上下文協議） 要解決的命題。

本文面向具備 Python 或 TypeScript 基礎的後端 / AI 工程師，從協議原理到生產部署，手把手帶你開發並上線一個可用的 MCP Server。讀完應能獨立實作 Tools、Resources、Prompts 三大能力，完成 Cursor / Claude Desktop 聯調，並跑通個人知識庫實戰專案。

01 MCP 協議原理：從 Function Calling 到統一工具調用

痛點拆解：現有 AI 模型「不夠聰明」的根源，往往是缺乏存取外部工具與即時資料的標準通道。各家 LLM 的 Function Calling 格式不同，換模型就要重寫整合層；LangChain Tools 綁定框架，無法跨 IDE 複用。

演進路徑：Function Calling（廠商私有）→ ChatGPT Plugins（平台鎖定）→ MCP（開放協議標準）。Anthropic 於 2024 年 11 月開源 MCP，目標是用一套 JSON-RPC 規範統一 AI 與外部系統的通訊。
架構角色：MCP Client（用戶端） 位於 AI 側（Claude Desktop、Cursor、自訂用戶端）；MCP Server（伺服器端） 是你開發的能力提供方。Server 向下對接資料庫、API、檔案系統，向上暴露三大核心能力：Tools（可呼叫函式）、Resources（可讀取資料）、Prompts（預定義提示詞範本）。
通訊機制：底層基於 JSON-RPC 2.0；傳輸支援 stdio（本機子程序，延遲極低）與 HTTP + SSE / Streamable HTTP（遠端多客戶端）。生命週期為：初始化握手 → 能力協商（tools/list 等）→ 請求/回應 → 優雅關閉。

MCP vs OpenAI Function Calling vs LangChain Tools
對照維度	MCP	OpenAI Function Calling	LangChain Tools
標準化程度	開放協議，跨模型	廠商私有	框架綁定
傳輸方式	stdio / HTTP	HTTP	HTTP
Resources / Prompts	原生支援	不支援	不支援
生態工具	2026 年 10000+ Server	成熟但鎖定 OpenAI	成熟但鎖定框架

寫一次 MCP Server，Cursor、Claude Desktop、VS Code 等相容用戶端均可呼叫——這才是 AI 工具化的「USB-C 時刻」。

02 開發環境建置與第一個 Hello World MCP Server

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

setup.sh

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

npm init -y
npm install @modelcontextprotocol/sdk

推薦專案結構：server.py（主入口）、tools/（計算機、搜尋等）、resources/（檔案讀取）、prompts/（範本）、tests/（單元測試）、pyproject.toml。

偵錯工具：官方 MCP Inspector（npx @modelcontextprotocol/inspector）提供視覺化 UI；Claude Desktop 透過 claude_desktop_config.json 聯調；Cursor 在 Settings → MCP 新增 Server 設定。

server.py

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 在 Inspector 中驗證 say_hello 出現在工具清單。設定 Cursor / Claude Desktop 後，AI 上下文應能發現並呼叫該工具。

03 Tools 開發：五類實用工具、非同步與錯誤處理

工具基本結構：函式簽名即文件——參數型別、回傳型別、docstring 會被轉為 JSON Schema 供 AI 理解。命名建議用 snake_case，動詞開頭（search_web、read_file）。

複雜參數：用 Pydantic BaseModel 定義輸入，支援預設值與欄位描述：

tools/web_search.py

from pydantic import BaseModel, Field

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

@mcp.tool()
def web_search(input: SearchInput) -> list[dict]:
    ...

五類實戰工具建議：

計算機：安全解析數學運算式（避免 eval 注入）。
檔案讀寫：限定允許存取的目錄白名單。
HTTP 請求：呼叫外部 REST API，注意逾時與回應大小限制。
資料庫查詢：唯讀 SQL + 參數化查詢，禁止 DDL。
時間工具：目前時間、時區轉換，Agent 排程必備。

非同步工具：IO 密集型操作用 async def + httpx.AsyncClient，避免阻塞 stdio 事件迴圈。錯誤處理優先回傳結構化錯誤字典（含 error、code 欄位），而非裸拋例外；為長任務設定逾時與權限校驗。

04 Resources 與 Prompts：資料供給與可複用範本

Resource vs Tool：Resource 是資料提供者（AI 讀取），Tool 是動作執行者（AI 呼叫）。Resource 透過 URI 尋址：file://、http://、custom://。

resources.py

@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:
    return json.dumps(db.query_user(user_id))

資源型別：文字（text/plain、application/json）、二進位（圖片、PDF）、串流（即時行情）。檔案系統資源伺服器可實作：列出目錄、讀取檔案、訂閱檔案變化（資源更新通知）。

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

05 HTTP 遠端傳輸、偵錯測試與生產部署

stdio vs HTTP + SSE 選型
特性	stdio	HTTP + SSE
部署	本機程序	遠端伺服器
多客戶端	不支援	支援團隊共享
適用場景	個人本機工具	SaaS / 團隊 MCP 服務

遠端部署範例：FastMCP("remote-server", transport="streamable-http")，配合 uvicorn 監聽 0.0.0.0:8000。生產須加固：Bearer Token、API Key 中介軟體、CORS 白名單、請求頻率限制。

偵錯：MCP Inspector 可測試 Tools 呼叫、檢視 JSON-RPC 日誌、模擬錯誤。單元測試透過 mcp.client.stdio 啟動子程序，session.call_tool 斷言回傳值。

常見錯誤排查
錯誤現象	原因	解決方案
工具未出現在 AI 中	設定路徑錯誤	檢查 mcp.json / claude_desktop_config.json
JSON 序列化失敗	回傳型別不支援	轉為 str 或 dict
逾時斷開	工具執行過慢	改非同步 + 設定逾時

生產部署：Docker 容器化（Python 3.12-slim 基礎映像檔）；Railway / Render 適合個人專案；AWS Lambda / Cloud Run 適合 Serverless；自建 VPS 配合 Nginx 反向代理。監控建議：結構化日誌、Prometheus 工具呼叫指標、Sentry 錯誤告警、/health 健康檢查。版本管理須宣告 MCP 協議版本，工具升級保持向後相容。

06 個人知識庫實戰、生態資料與六步落地

實戰專案：個人知識庫 MCP Server——讓 AI 搜尋本機 Markdown 筆記、語意檢索、建立與更新筆記。技術選型：ChromaDB / Qdrant 作向量庫，text-embedding-3-small 作嵌入模型，watchfiles 監聽檔案變化自動重建索引。核心實作：筆記索引工具、語意搜尋工具、筆記寫入工具、檔案 Resource 服務。在 Cursor 中問「我上週記錄了什麼關於 MCP 的筆記？」，Agent 呼叫搜尋工具回傳相關片段。

2026 優質 MCP Server 推薦：mcp-server-filesystem、mcp-server-github、mcp-server-brave-search、mcp-server-postgres、mcp-server-slack。主流用戶端（Cursor、Claude Desktop、VS Code、Gemini）均已原生支援 MCP；企業級安全標準與 MCP Marketplace 生態持續成熟。

可引用資料：

協議發布：Anthropic 2024 年 11 月開源 MCP，底層 JSON-RPC 2.0，2026 年治理權移交 Linux Foundation AAIF。
生態規模：公開 MCP Server 已超過 10,000 個；Python SDK 與 TypeScript SDK 為官方維護主線（發版後請開啟 GitHub 核對最新版本）。
傳輸演進：Streamable HTTP 逐步取代純 SSE，更適合無狀態負載平衡與雲原生部署。

官方文件與 SDK（發版後請再次開啟連結核對）：

https://modelcontextprotocol.io

https://github.com/modelcontextprotocol/python-sdk

https://github.com/modelcontextprotocol/typescript-sdk

https://github.com/modelcontextprotocol/inspector

選定語言與傳輸模式：個人開發用 Python + stdio；團隊共享選 HTTP + Streamable HTTP。
搭建專案骨架：按 tools / resources / prompts 分模組，安裝 MCP Inspector。
實作 Hello World 並聯調：在 Cursor 或 Claude Desktop 驗證工具可見、可呼叫。
擴展五類 Tools + Resource：從低風險唯讀工具起步，逐步加寫入與外部 API。
撰寫單元測試與 Docker 映像檔：CI 中跑 stdio 整合測試，建構可部署映像檔。
部署到 7×24 線上環境：本機筆電闔蓋休眠會斷開 MCP 工作階段；純 Linux VPS 缺少 macOS 沙箱與 Xcode 生態。對需要穩定 MCP 基礎設施、多成員共享 Agent 與 iOS CI 的生產場景，CALMVPS 裸金屬 Mac 租賃 通常是更優解：獨占 M4/M4 Pro、約 120 秒交付、彈性日/週/月/季租。機型見定價頁，遠端接入見幫助中心。

MCP 是 AI 工具化的標準協議——掌握它，你就擁有了為任意 LLM 擴展真實世界能力的基礎設施技能。你打算用 MCP 開發什麼工具？從今天的 Hello World 開始。

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