為 Claude Code 建立 MCP Server — 實用的分步指南

Model Context Protocol（MCP）是一種開放標準，讓像 Anthropic 的Claude這樣的模型以及像Claude Code這樣的開發者工具，能以安全、標準化的方式呼叫外部工具、資料來源與提示。

本指南將帶你從零開始建立自己的 MCP 伺服器，使 Claude Code 能存取自訂功能，將其能力大幅擴充至內建功能之外。

什麼是 Model Context Protocol（MCP）？

MCP（Model Context Protocol）是一個開放規範，用於標準化語言模型客戶端（如 Claude、Claude Code 或其他 LLM 前端）如何連接到工具伺服器和資料來源。把 MCP 想像成 LLM 的「USB-C 埠」：它定義了傳輸/JSON-RPC 結構，以及伺服器以一致方式發布三類能力：

• Resources（資源） —— 類似檔案或文件的資料，供客戶端讀取（例如資料庫列、文字檔、JSON 載荷）。
• Tools（工具） —— 可呼叫的函式，模型可要求主機執行（需使用者同意）。
• Prompts（提示） —— 可重用的提示模板或工作流程，供模型/客戶端調用。

MCP 支援多種傳輸（stdio、HTTP、SSE），並提供結構、SDK 與範例伺服器，讓你無需自行發明線路格式。該協議以公開方式維護（規範+SDK），並有教學與範例伺服器集，促進採用。

MCP 的架構如何設計？

MCP 的架構刻意保持簡潔與模組化：核心組件是 MCP 伺服器、MCP 客戶端，以及在它們之間承載 JSON-RPC 封裝訊息的傳輸層。以下是當你為 Claude Code（或其他 MCP 客戶端）建立伺服器時會接觸的主要元件。

伺服器、客戶端與協議

• MCP 伺服器 —— 一個會「發布」工具、資源與提示的服務。工具可執行副作用或抓取資料；資源提供唯讀內容；提示是客戶端可請模型重用的提示模板。
• MCP 客戶端（宿主） —— 通常是 LLM 宿主的一部分（例如 Claude Code、VS Code 外掛、瀏覽器客戶端）。它會發現可用伺服器、將工具描述呈現給模型，並將模型啟動的呼叫路由到伺服器。
• 協議 —— 訊息以 JSON-RPC 編碼；規範定義了生命週期事件、工具探索、調用、補全/採樣，以及如何將結構化結果傳回客戶端與模型。

通訊流程（使用工具時會發生什麼）

1. 客戶端將使用者訊息傳給模型。
2. 模型分析情境並決定呼叫由 MCP 暴露的工具（或多個工具）。
3. 客戶端透過所選傳輸，將工具呼叫轉送到 MCP 伺服器。
4. 伺服器執行該工具並返回結果。
5. 模型接收工具輸出並組合成給使用者的最終答案。

實作基礎要素

• JSON-RPC 訊息遵循 MCP 結構。
• 工具定義 會在伺服器的探索回應中發布，讓客戶端能在 UI 中呈現。
• 資源 在客戶端以 @source:path 語法引用（例如 @postgres:...），讓模型能引用外部內容，而不必將大量資料直接內嵌到提示中。

為何將 Claude Code 與 MCP 伺服器整合？

Claude Code 是 Anthropic 專注於程式碼與開發者工作流程（編輯器/IDE 整合、程式碼理解等）的產品。透過 MCP 伺服器暴露你的內部工具（原始碼搜尋、CI 執行器、工單系統、私有套件註冊表），讓 Claude Code 能在編碼對話與代理流程中，將它們作為一等公民工具來呼叫。

將 Claude Code 與 MCP 伺服器整合能為程式代理解鎖貼近生產環境的實用能力：

1. 讓模型在真實系統上執行動作

Claude Code 可請 MCP 伺服器查詢議題追蹤、執行資料庫查詢、讀取大型文件，或產生 GitHub PR —— 使你能在同一編碼階段內完成端到端自動化。這在 Claude Code 文件中有明確支持（例如查詢 Postgres、Sentry 或建立 PR 的範例）。

2. 將大量資料與專門邏輯卸載到伺服器

不必將每個資料來源嵌入提示（會消耗 tokens），你可以透過 MCP 發布資料與工具。模型呼叫工具、取得結構化回應並據此推理——這能降低 token 使用量，並讓伺服器處理繁重工作（資料庫查詢、長檔案讀取、驗證）。

3. 安全與治理

MCP 將存取控制與稽核集中在伺服器層，讓組織可加入白名單伺服器、控管可用工具並限制輸出。Claude Code 也支援企業級 MCP 設定與依範圍同意。

4. 可重用性與生態系

MCP 伺服器可在不同客戶端與團隊間重用。一次建置，多個 Claude/LLM 客戶端可使用同一服務（或替換實作）。

開始前需要什麼？

最低需求

• 具備 Python 3.10+ 的開發機（示例採用 Python）。另有 Node／其他語言的 MCP SDK 支援。
• uv（Astral 的工具）或同類執行器，用於執行 MCP stdio 伺服器（MCP 教程使用 uv）。安裝步驟見下方。
• 已安裝 Claude Code 或可存取 Claude 客戶端（桌面或 CLI），用來註冊並測試你的伺服器；或任何 MCP 相容客戶端。Claude Code 支援 HTTP、SSE 與本地 stdio 伺服器。
• 安全注意事項：在團隊或企業環境中，只將可信的 MCP 伺服器加入 Claude Code —— MCP 賦予伺服器存取敏感資料的能力；若伺服器返回惡意內容，亦存在提示注入風險。

如何安裝並驗證 Claude Code CLI

這是Claude Code 安裝與使用指南。

1) 快速摘要 —— 推薦安裝方式

使用原生安裝程式（推薦）或 macOS/Linux 上的 Homebrew。若需要 Node 式安裝，可用 NPM。Windows 提供 PowerShell / CMD 安裝程式。資料來源：官方 Claude Code 文件與 GitHub。

---

2) 先決條件

• macOS 10.15+、Ubuntu 20.04+/Debian 10+，或 Windows 10+（Windows 建議使用 WSL）。
• 僅在使用 NPM 安裝方式時，才需要 Node.js 18+。

---

3) 安裝指令（擇一）

原生（推薦 —— 無 Node 依賴），macOS / Linux / WSL：

curl -fsSL https://claude.ai/install.sh | bash
# optional: install latest explicitly

curl -fsSL https://claude.ai/install.sh | bash -s latest
# or install a specific version

curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

Windows PowerShell：

irm https://claude.ai/install.ps1 | iex
# or for latest: & (::Create((irm https://claude.ai/install.ps1))) latest

（以上為官方原生安裝腳本）。

NPM（若你需要 Node 式的全域安裝）：

# requires Node.js 18+

npm install -g @anthropic-ai/claude-code

請勿使用 sudo npm install -g —— 警告：sudo 全域安裝會帶來權限/安全問題。若遇到權限錯誤，請使用 nvm 或修正 npm 的全域安裝路徑，而非使用 sudo。

4) 驗證二進位檔是否已安裝（基本檢查）

安裝後立刻在本機執行：

# is the command on PATH?

which claude

# version (or -v)

claude --version
# or

claude -v

# help (sanity check)

claude --help

預期：which 會顯示一個路徑（例如 /usr/local/bin/claude 或 ~/.nvm/.../bin/claude），而 claude --version 會印出類似 semver 的版本字串。文件與 README 都顯示 claude 為主要的 CLI 入口命令。

---

5) 驗證安裝狀態與設定（建議檢查）

a) claude doctor，執行：

claude doctor

這個內建診斷工具會檢查你的安裝方式、常見問題（例如 npm 權限問題）、依賴項如 ripgrep，並提出修復建議。文件明確建議安裝後執行 claude doctor。

b) 執行煙霧測試（非互動）

在你的專案目錄：

cd /path/to/your/project
claude -p "Explain this project in 3 sentences"

這會使用列印模式（-p），送出單一提示後即退出；適合用於 CI 或快速功能檢查。

c) 驗證身份（確認 CLI 能連到 Anthropic）

Claude Code 支援多種認證流程（Console OAuth、API 金鑰、供應商整合）。常見檢查：

1. 若使用 API 金鑰（CI / 無頭 / 本地環境變數）：

export ANTHROPIC_API_KEY="sk-..."
# then

claude auth status
claude auth whoami    # or `claude auth whoami` / `claude whoami` depending on version

你可以使用 CometAPI 的 API 金鑰來使用 Claude Code。透過 CometAPI 使用 Claude 的 API 可享 20% 折扣。

2. 若透過主控台的 OAuth —— 執行：

claude auth status
claude auth whoami

你應該會看到帳戶/方案資訊，或已通過驗證的確認訊息。

逐步環境準備

以下為兩個常見開發堆疊（TypeScript 與 Python）的具體步驟，並附上快速檢查以確保一切正常。

H3 — A. TypeScript / Node 設定（最快捷徑）

1. 建立專案並安裝 SDK：

mkdir mcp-demo && cd mcp-demo
npm init -y
npm install @modelcontextprotocol/sdk express zod
npm install --save-dev typescript tsx @types/node @types/express

2. 建立 server.ts。（完整範例見「如何快速建置…」段落。）
3. 執行：

npx -y tsx server.ts

4. 使用 MCP Inspector 在本地測試，或加入到 Claude Code：

npx @modelcontextprotocol/inspector
# or (for Claude Code)

claude mcp add --transport http my-server http://localhost:3000/mcp

（Inspector 與 Claude 指令可用來驗證探索並調用工具。）

如何為 Claude Code 快速建置 MCP 伺服器？

快速檢查清單

1. 啟動你的伺服器（建議使用可串流 HTTP）：node server.ts 或 uvicorn server:app。

2. 在你的開發機上，擇一：

• 使用 MCP Inspector 進行驗證（npx @modelcontextprotocol/inspector），並確認 tools/list 與 resources/list；或
• 將伺服器加入 Claude Code：claude mcp add --transport http <name> http://<host>:<port>/mcp（若你的客戶端支援遠端 MCP，也可依照網頁 UI 流程）。

若你計畫使用 Anthropic 的 Messages API 連接器來進行遠端 MCP（無需額外客戶端），請參閱 Claude 文件 —— 可能需要測試版標頭（請查閱文件以取得確切標頭與目前支援狀態）。

以下提供兩個完整且精簡的伺服器範例，可直接複製、執行，並連接到 Claude Code（或 MCP Inspector）。TypeScript 範例使用 Express + TypeScript SDK；Python 範例則展示 FastAPI 的掛載方式。

注意：以下程式碼遵循公開 SDK 範例，並刻意保持最小化以利說明。用於生產環境時，請加入驗證、記錄、速率限制與更嚴謹的輸入驗證（超出 SDK 預設）。

---

範例 1：TypeScript + Express（可串流 HTTP）

建立 server.ts（完整）：

// server.ts
import express from "express";
import * as z from "zod/v4";
import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

const server = new McpServer({ name: "claude-code-demo", version: "0.1.0" });

// Register a simple tool: add two numbers
server.registerTool(
  "add",
  {
    title: "Add",
    description: "Add two numbers a and b",
    inputSchema: { a: z.number(), b: z.number() },
    outputSchema: { result: z.number() }
  },
  async ({ a, b }) => {
    const output = { result: a + b };
    return {
      content: ,
      structuredContent: output
    };
  }
);

// Register a resource: greet user (dynamic)
server.registerResource(
  "greeting",
  new ResourceTemplate("greeting://{name}", { list: undefined }),
  { title: "Greeting", description: "Return a greeting for the name" },
  async (uri, params) => {
    return {
      contents: 
    };
  }
);

// Express + Streamable HTTP transport
const app = express();
app.use(express.json());

app.post("/mcp", async (req, res) => {
  const transport = new StreamableHTTPServerTransport({ enableJsonResponse: true });
  // Close transport when connection closes
  res.on("close", () => transport.close());
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

const port = parseInt(process.env.PORT || "3000", 10);
app.listen(port, () => console.log(`MCP server listening: http://localhost:${port}/mcp`));

執行：

npm install
npx -y tsx server.ts

然後在 Claude Code 中連接（示例）：

# Add the remote server to your Claude Code MCP list (local dev)

claude mcp add --transport http my-demo http://localhost:3000/mcp

此範例改編自官方 TypeScript SDK 快速上手，示範如何註冊工具與資源，並透過可串流 HTTP 對外暴露。

---

範例 2：Python + FastAPI（FastMCP + 可串流 HTTP）

建立 server.py（完整）：

# server.py

from fastapi import FastAPI
from mcp.server.fastmcp import FastMCP

app = FastAPI()
mcp = FastMCP("claude-python-demo", stateless_http=True)

# tool: simple sum

@mcp.tool()
def add(a: int, b: int) -> dict:
    """Add two integers"""
    return {"result": a + b}

# resource: simple greeting resource template

@mcp.resource("greeting://{name}")
def greeting(name: str):
    return {"contents": }

# mount the streamable-http MCP endpoint (FastMCP exposes an ASGI app)

app.mount("/mcp", mcp.streamable_http_app())

# optional endpoint to demonstrate other API routes

@app.get("/")
async def root():
    return {"status": "OK"}

執行：

uvicorn server:app --reload --port 8000

使用 Inspector 連接：

npx @modelcontextprotocol/inspector
# In Inspector select Streamable HTTP and enter http://localhost:8000/mcp

Python SDK 範例與 FastMCP 工具讓你能輕鬆註冊以 @mcp.tool() 與 @mcp.resource() 裝飾的函式，供 LLM 探索與呼叫。

---

Claude Code 實際如何呼叫你的工具？

當 LLM 判定需要使用工具時，客戶端會向 MCP 伺服器送出 JSON-RPC 調用。伺服器執行所要求的工具（例如查詢資料庫、執行測試或呼叫外部 API），並返回結構化內容與可呈現內容。客戶端（Claude Code）隨後可將結構化輸出加入模型的上下文，使模型能以可信資料持續推理——而非僅依賴伺服器的文字輸出。TypeScript SDK 支援註冊 inputSchema 與 outputSchema（zod），因此引數與輸出都能被驗證並具備機器可讀型別。

---

該用哪些測試與除錯工具？

MCP Inspector

MCP Inspector 是官方的視覺化開發工具，用於測試 MCP 伺服器。它允許你連接到伺服器（stdio、SSE 或可串流 HTTP）、列出工具、手動調用，並檢視 JSON-RPC 訊息的生命週期 —— 是開發過程中不可或缺的工具。透過 npx @modelcontextprotocol/inspector 啟動。

本地 vs 遠端測試

• 本地（stdio） —— 適合桌面應用與離線除錯，迭代快速。
• 可串流 HTTP —— 使用 Inspector 測試，或透過 claude mcp add CLI 或 Messages API 的 MCP 連接器連接到 Claude Code 進行遠端測試。請確保提供伺服器所需的任何驗證標頭。

結論

MCP 是連接現代 LLM 與真正承載資料與執行動作之系統的實用橋樑。對於程式碼工作流程而言，將 Claude Code 與 MCP 伺服器整合，能為模型提供結構化、可稽核的存取至版本庫、CI、議題追蹤與自訂工具 —— 帶來更精準的自動化與更安全的副作用。藉助官方的 TypeScript 與 Python SDK、可串流 HTTP 以支援遠端部署，以及 MCP Inspector 等工具，你可以在幾分鐘內建置最小伺服器，並逐步迭代到生產部署。

開發者可以透過 CometAPI 存取 Claude Sonnet 4.5 API 和 Claude Opus 4.1 API 等，最新的模型版本 會與官方網站保持同步更新。開始前，請先在 Playground 探索模型能力，並參閱 API guide 取得詳細指引。使用前請先登入 CometAPI 並取得 API 金鑰。CometAPI 提供遠低於官方的價格，協助你整合。

Ready to Go?→ Sign up for CometAPI today！

若你想獲取更多 AI 技巧、指南與新聞，歡迎在 VK、X 與 Discord 關注我們！