Claude Code 的 MCP Server：讓 AI 連接你的資料來源

這是 Claude Code 系列的進階篇。建議先閱讀： 📖 打造 AI 友善的專案文檔：CLAUDE.md 完整指南（上） 📖 Claude Code 權限控管：用 settings.local.json 保護你的專案

🎯 前言

用 Claude Code 寫程式時，你可能碰過這個情境：

我：幫我查一下 issue-042 的內容
Claude：我無法存取你的 issue tracker，請把內容貼給我

Claude Code 本身只能操作本機檔案和終端指令。它看不到你的 Jira、碰不到你的資料庫、讀不了你的 Slack 訊息。

MCP（Model Context Protocol）就是解決這個問題的機制。

MCP 是 Anthropic 設計的開放協定，讓 AI 工具透過一個統一的介面連接外部資料來源。你可以把它想成 AI 世界的 USB-C——不管是資料庫、GitHub、Slack 還是自己寫的 API，都用同一個協定接上去。

📂 MCP 的架構

MCP 採用 client-host-server 模型：

┌─────────────────────────────────────┐
│  Claude Code（Host）                 │
│                                     │
│  ┌──────────┐  ┌──────────┐        │
│  │ Client 1 │  │ Client 2 │  ...   │
│  └────┬─────┘  └────┬─────┘        │
│       │              │              │
└───────┼──────────────┼──────────────┘
        │              │
   ┌────▼─────┐  ┌────▼─────┐
   │ MCP      │  │ MCP      │
   │ Server A │  │ Server B │
   │ (GitHub) │  │ (DB)     │
   └──────────┘  └──────────┘
  • Host：Claude Code，負責管理所有連線
  • Client：Host 內部的連接器，每個 client 對接一個 server
  • Server：提供工具（tools）、資源（resources）、提示（prompts）的服務

通訊使用 JSON-RPC 2.0，建立連線時會做能力協商（capability negotiation）。

三種傳輸方式

傳輸方式說明適用場景
stdio標準輸入/輸出本機工具、CLI 程式
Streamable HTTP單一 HTTP 端點雲端服務、遠端 API（推薦）
SSEServer-Sent Events已棄用，用 HTTP 取代

選擇原則：跑在你的機器上 → 用 stdio。跑在遠端 → 用 HTTP。

⚙️ 在 Claude Code 中設定 MCP Server

用 CLI 新增

最快的方式是用 claude mcp add 指令：

# 本機 stdio server
claude mcp add --transport stdio my-db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@localhost:5432/mydb"

# 遠端 HTTP server
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 帶環境變數
claude mcp add --transport stdio github-mcp -- \
  npx -y @anthropic/mcp-github \
  --env GITHUB_TOKEN=ghp_xxxxxxxxxxxx

Windows 注意：用 npx 的 stdio server 需要加 cmd /c：

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

用 JSON 新增

也可以直接傳 JSON 設定：

claude mcp add-json local-db '{"type":"stdio","command":"npx","args":["-y","@bytebase/dbhub","--dsn","postgresql://user:pass@localhost:5432/db"]}'

管理指令

claude mcp list          # 列出所有 server
claude mcp get my-db     # 查看特定 server 的設定
claude mcp remove my-db  # 移除 server

在 Claude Code session 中，輸入 /mcp 可以查看所有 MCP server 的連線狀態。

設定檔位置

MCP 設定存在幾個地方，優先級由高到低：

位置影響範圍用途
~/.claude.json（per-project 區段）單一專案，個人預設（claude mcp add 寫入這裡）
.mcp.json（專案根目錄）單一專案，共享提交到 git，團隊共用
~/.claude.json（global 區段）所有專案claude mcp add -s user

.mcp.json 的格式

如果要讓團隊共用 MCP 設定，在專案根目錄建立 .mcp.json：

{
  "mcpServers": {
    "project-db": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DB_DSN}"],
      "env": {
        "DB_DSN": "${DB_DSN}"
      }
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

環境變數支援 ${VAR} 和 ${VAR:-default} 語法。敏感資訊（密碼、token）用環境變數帶入，不要寫死在設定檔中。

🛠️ 實用的 MCP Server 範例

範例 1：連接 PostgreSQL

讓 Claude 可以查詢你的資料庫（建議用唯讀帳號）：

claude mcp add --transport stdio project-db -- \
  npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@localhost:5432/analytics"

設定好之後：

我：查一下 users 表有多少筆資料
Claude：我來查詢資料庫...
（使用 mcp__project-db__query 工具）
users 表目前有 12,847 筆資料。

安全建議：一定要用唯讀帳號。Claude 有可能嘗試 DROP TABLE，唯讀帳號是最後的防線。

範例 2：連接 GitHub

讓 Claude 可以查看 issue、PR、程式碼：

claude mcp add --transport http github \
  https://api.githubcopilot.com/mcp/

設定好之後：

我：幫我看一下 PR #42 的 review comments
Claude：（使用 mcp__github__get_pull_request_comments 工具）
PR #42 有 3 則 review comment...

範例 3：連接 Sentry（錯誤監控）

讓 Claude 可以查看 production 的錯誤記錄：

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

除錯時特別好用——Claude 可以直接看到錯誤的 stack trace、影響範圍、發生頻率。

範例 4：連接 Notion

讓 Claude 讀取你的技術文件：

claude mcp add --transport http notion https://mcp.notion.com/mcp

🔨 自己寫一個 MCP Server

如果現成的 MCP server 不符合你的需求，可以自己寫一個。兩種語言都有官方 SDK。

Python 版（用 FastMCP）

pip install "mcp[cli]"
# my_server.py
from mcp.server.fastmcp import FastMCP

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

@mcp.tool()
async def search_issues(keyword: str) -> str:
    """搜尋 issue tracker 中包含關鍵字的 issue。
    
    Args:
        keyword: 搜尋關鍵字
    """
    # 這裡接你自己的 issue tracker API
    results = await fetch_from_tracker(keyword)
    return format_results(results)

@mcp.tool()
async def get_deploy_status(env: str) -> str:
    """查詢指定環境的部署狀態。
    
    Args:
        env: 環境名稱（staging / production）
    """
    status = await check_deployment(env)
    return f"{env}: {status}"

def main():
    mcp.run(transport="stdio")

if __name__ == "__main__":
    main()

註冊到 Claude Code：

claude mcp add --transport stdio my-tracker -- python my_server.py

TypeScript 版

npm install @modelcontextprotocol/sdk zod
// server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "my-custom-server",
  version: "1.0.0",
});

server.tool(
  "search_issues",
  { keyword: z.string().describe("搜尋關鍵字") },
  async ({ keyword }) => {
    const results = await fetchFromTracker(keyword);
    return {
      content: [{ type: "text", text: JSON.stringify(results) }],
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

MCP Server 能暴露什麼？

類型說明在 Claude Code 中怎麼用
Tools可執行的函數Claude 自動呼叫（需要用戶確認）
Resources檔案式的資料用 @server:protocol://path 引用
Prompts範本化的工作流變成 /mcp__servername__promptname 指令

大多數情況只需要定義 tools 就夠了。

🔑 安全考量

MCP server 等於讓 Claude 能存取外部系統，安全性必須謹慎處理。

最小權限原則

✅ 用唯讀帳號連資料庫
✅ GitHub token 只給必要的 scope
✅ API key 設定最小存取範圍

❌ 用 root 帳號連資料庫
❌ GitHub token 給 admin 權限
❌ 用不受限的 API key

敏感資訊不要寫死

// ❌ 不要這樣做
{
  "command": "npx",
  "args": ["--dsn", "postgresql://root:real_password@prod:5432/db"]
}

// ✅ 用環境變數
{
  "command": "npx",
  "args": ["--dsn", "${DB_DSN}"],
  "env": {
    "DB_DSN": "${DB_DSN}"
  }
}

.mcp.json 的信任問題

如果你 clone 了一個陌生的 repo，裡面的 .mcp.json 可能設定了惡意的 MCP server。

Claude Code 的防護機制：第一次使用專案中的 .mcp.json 時會詢問你是否信任。 不認識的 repo，仔細看一下 .mcp.json 的內容再放行。

搭配權限設定使用

在 settings.local.json 中，你可以用 deny 規則限制特定 MCP 工具：

{
  "permissions": {
    "deny": [
      "mcp__project-db__execute_query"
    ]
  }
}

💡 Tool Search：降低 Context 壓力

如果你安裝了很多 MCP server，每個 server 的工具描述都會佔用 context window。Claude Code 的 Tool Search 機制可以緩解這個問題：

  • 啟動時只載入工具名稱，不載入完整的參數 schema
  • Claude 需要用到某個工具時，才動態載入完整定義
  • 預設開啟，不需要額外設定

如果你的 MCP server 超過 10 個，Tool Search 會明顯減少 context 的消耗。

⚠️ 常見問題

Server 啟動失敗

最常見的原因是 timeout。預設的啟動 timeout 可能不夠，特別是 npx 第一次執行需要下載套件時：

# 設定環境變數增加 timeout
MCP_TIMEOUT=30000 claude

Windows 的 npx 問題

Windows 上直接用 npx 的 stdio server 會失敗，需要用 cmd /c 包裝：

# ❌ 會失敗
claude mcp add --transport stdio my-server -- npx -y some-package

# ✅ 正確做法
claude mcp add --transport stdio my-server -- cmd /c npx -y some-package

輸出太大

MCP 工具的回傳內容超過 10,000 tokens 時會警告，超過 25,000 tokens 會被截斷。

如果你的資料庫查詢會回傳大量資料，在 MCP server 的 tool 實作中加上 LIMIT：

@mcp.tool()
async def query_users(keyword: str) -> str:
    """搜尋使用者（最多回傳 50 筆）"""
    results = db.execute(
        "SELECT id, name FROM users WHERE name LIKE %s LIMIT 50",
        (f"%{keyword}%",)
    )
    return format_results(results)

和 Claude Desktop 共用設定

如果你已經在 Claude Desktop 設定了 MCP server，可以直接匯入：

claude mcp add-from-claude-desktop

目前只支援 macOS 和 WSL。

📋 我的 MCP 使用建議

階段建議
剛開始先試一個現成的 server（GitHub 或資料庫），體驗 MCP 的效果
有需求找不到現成的再自己寫，Python FastMCP 最快上手
團隊使用把設定放進 .mcp.json，敏感資訊用環境變數
安全永遠用最小權限，搭配 settings.local.json 的 deny 規則

MCP 生態系已經有超過 400 個社群建置的 server。在自己寫之前，先搜尋看看有沒有現成的。官方的 MCP server 列表在 github.com/modelcontextprotocol/servers。

🎉 結語

MCP 讓 Claude Code 從「只能操作本機檔案」變成「可以連接任何外部系統」。

和之前介紹的幾個機制放在一起看：

機制解決什麼
CLAUDE.mdClaude 怎麼理解你的專案
settings.local.jsonClaude 能用哪些工具
Slash CommandsClaude 怎麼執行工作流程
Hooks在 Claude 動作時自動觸發腳本
MCP Server讓 Claude 存取外部資料來源

五個機制各管一塊，合在一起就是一個完整的 AI 開發環境。

📎 相關文章：