用法

Claude Code MCP 配置教程：新增、共享和排查 MCP 伺服器

釋出於 2026 年 10 月 30 日 · 最後核對 2026 年 10 月 30 日

MCP（Model Context Protocol）是連線 AI 工具的開源標準，MCP 伺服器能讓 Claude Code 直接讀寫你的工具、資料庫和 API，不用再把資料複製進對話。這一頁是新增 MCP 伺服器的操作步驟：三種連線方式各用哪條命令、配置存在哪裡、怎麼和團隊共享、怎麼認證、出錯了看什麼。內容按 Anthropic 的 Connect Claude Code to tools via MCP 中文整理，2026 年 10 月 30 日對照原文核對。

MCP 是什麼，什麼時候該接

MCP 伺服器讓 Claude Code 能訪問你的工具、資料庫和 API。當你發現自己在把另一個工具裡的資料（比如工單系統或監控面板）複製進對話時，就適合接一個伺服器：接上之後，Claude 可以直接讀取、操作那個系統，不用再依賴你貼過來的內容。

安全提醒：連線任何伺服器之前，先確認你信任它。會抓取外部內容的伺服器可能讓你暴露在提示詞注入風險下。

三種連線方式怎麼新增

所有方式都用 claude mcp add。先看伺服器給的是什麼：一個 https:// 地址是遠端伺服器，一條 npx 之類的啟動命令是跑在你本機的伺服器。

遠端 HTTP 伺服器

# 基本寫法
claude mcp add --transport http <name> <url>

# 官方示例：連線 Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 帶 Bearer token 的示例
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

在 JSON 裡配置時，type 欄位可以寫 streamable-http，它是 http 的別名。有 url 卻沒有 type 的條目是配置錯誤，因為 Claude Code 會把沒有 type 的條目當成 stdio 伺服器，並跳過它。

遠端 SSE 伺服器

SSE（Server-Sent Events）傳輸已棄用，有 HTTP 的地方請用 HTTP。有些服務仍然只提供 SSE 端點：這時仍然用上面的 claude mcp add --transport http <name> <url>，Claude Code 會先嚐試 HTTP，伺服器不接受時自動切到 SSE。這個自動切換需要 Claude Code v2.1.265 或更高版本。更早的版本，或想直接用 SSE，傳 --transport sse：

# 基本寫法
claude mcp add --transport sse <name> <url>

# 官方示例：連線 Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# 帶認證 header 的示例
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

本地 stdio 伺服器

stdio 伺服器作為本地程式執行在你的機器上。

# 基本寫法
claude mcp add [options] <name> -- <command> [args...]

# 官方示例：新增 Airtable 伺服器
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

• --（雙橫線）把 Claude 自己的選項（比如 --transport、--env、--scope）和啟動伺服器的命令分開，-- 之後的內容原樣交給伺服器。不寫 --，Claude Code 會把伺服器的引數（比如 --port）當成自己的選項去解析。
• claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080 會執行 python server.py --port 8080，並把 KEY=value 放進環境變數。
• --env 可以接多個 KEY=value。如果伺服器名緊跟在 --env 後面，命令列會把名字當成又一對引數而報錯，所以在 --env 和伺服器名之間至少放一個別的選項，比如 --transport stdio。

從別的客戶端的安裝說明改寫

伺服器的安裝說明可能是為 Claude Desktop、Cursor 或其他 MCP 客戶端寫的，沒有 claude mcp add 命令。這時在說明裡找一個 URL、一條啟動命令或一段 JSON：

• URL（例如 https://mcp.example.com/mcp）：遠端伺服器，用 claude mcp add --transport http example https://mcp.example.com/mcp。
• 啟動命令（例如 npx -y @example/mcp-server）：跑在本機，把整條命令放在 -- 後面：claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server。
• mcpServers JSON 塊：把 mcpServers 裡面的物件（不含外層）交給 claude mcp add-json：

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

用 add-json 時，沒有 type 的 url 條目要先補上 "type": "http"、"type": "sse" 或 "type": "ws"。WebSocket 伺服器只能用 .mcp.json 或 claude mcp add-json 配置，claude mcp add --transport 不接受 ws。伺服器名只能包含字母、數字、連字元和下劃線。

作用域：配置存在哪裡

MCP 伺服器有三個作用域，決定它在哪些專案里載入，以及配置是否和團隊共享。用 -s 或 --scope 選擇，預設是 local。

# local 作用域（預設）
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

# project 作用域
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# user 作用域
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

local 作用域的伺服器存在 ~/.claude.json 裡該專案路徑下，不會出現在你的其他專案裡，適合個人開發伺服器、實驗性配置，以及帶憑據、不想進版本控制的伺服器。注意，這裡的 “local” 和一般設定裡的 .claude/settings.local.json 不是一回事。

同一個伺服器在多個地方定義時，Claude Code 只連一次，用優先順序最高的那份，整條配置原樣採用，不會跨作用域合併欄位。優先順序從高到低：local、project、user、外掛提供的伺服器、claude.ai 聯結器。

用 .mcp.json 和團隊共享

project 作用域把配置存進專案根目錄的 .mcp.json。新增 project 作用域的伺服器時，Claude Code 會自動建立或更新這個檔案。把它提交進版本控制，團隊裡每個人都會得到同樣的 MCP 工具。

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

出於安全考慮，互動工作階段在使用 .mcp.json 裡的伺服器之前會先請你批准。想重置這些批准的選擇，執行 claude mcp reset-project-choices。

在 .mcp.json 裡用環境變數

.mcp.json 支援環境變數展開，團隊可以共享同一份配置，而每臺機器上不同的路徑和 API key 這類敏感值留在各自的環境裡。可以在伺服器的 command、args、env、url 或 headers 裡引用：

• ${VAR}：展開為環境變數 VAR 的值。
• ${VAR:-default}：VAR 已設定時取它的值，未設定時取 default。

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

引用的變數沒設定又沒有預設值時，配置仍會載入，Claude Code 在 claude mcp list 裡給出缺少變數的警告，並按字面使用未展開的 ${VAR}。在遠端伺服器的 url 和 headers 裡，ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 這類憑據變數會被讀成空值，不會展開。要給伺服器這類憑據，先把它複製到一個自己命名的變數裡，再引用這個變數。

檢視、檢查和刪除伺服器

# 列出所有已配置的伺服器
claude mcp list

# 檢視某個伺服器的詳情
claude mcp get notion

# 刪除伺服器
claude mcp remove notion

# （在 Claude Code 裡）檢視伺服器狀態
/mcp

claude mcp add 成功時會列印一行 Added ...，表示配置已寫入；它不驗證憑據，所以填一個佔位的 token 也會透過，但之後連線會失敗。要確認 Claude Code 真的連上了，執行 claude mcp get <name>，或在 Claude Code 裡執行 /mcp，看那個伺服器那一行有沒有對勾。

claude mcp list 在每個伺服器旁邊顯示健康狀態：

刪除遠端伺服器時，Claude Code 會同時刪掉它為該伺服器儲存的 OAuth 令牌和客戶端註冊，但不會去授權伺服器上吊銷令牌。如果授權伺服器支援吊銷，先在 shell 裡執行 claude mcp logout <name>，再執行 claude mcp remove <name>。

想暫時停用而不刪除配置，在 /mcp 面板裡把伺服器關掉，Claude Code 就不再連線它，配置保留。

遠端伺服器的認證

很多雲端 MCP 伺服器需要認證，Claude Code 支援 OAuth 2.0。伺服器返回 401 Unauthorized 或 403 Forbidden 時，Claude Code 會把它標成需要認證。

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

然後在 Claude Code 裡執行 /mcp，按瀏覽器裡的步驟登入。

• 認證令牌會被安全儲存並自動重新整理。
• 在 /mcp 選單裡選 “Clear authentication” 可以撤銷訪問。
• 瀏覽器沒有自動開啟時，複製給出的 URL 手動開啟。
• 認證後瀏覽器重定向報連線錯誤時，把瀏覽器位址列裡完整的回撥 URL 貼上到 Claude Code 彈出的 URL 提示裡。
• OAuth 認證適用於 HTTP 伺服器。

不想進工作階段，可以直接在 shell 裡登入：

claude mcp login sentry

清除已儲存的憑據用 claude mcp logout <name>。在 SSH 工作階段或沒有顯示伺服器的 Linux 上，claude mcp login 檢測到沒有本地瀏覽器，會列印授權 URL 而不是去開啟瀏覽器：在你本機開啟這個 URL，再把瀏覽器位址列裡完整的重定向 URL 貼上回提示處，這一步需要互動終端，所以用 ssh -t 連線。加 --no-browser 可以強制使用 URL 提示。

如果你給伺服器配置了 headers.Authorization 而伺服器拒絕了它，Claude Code 會報連線失敗，不會退回到 OAuth。檢查令牌對這個 MCP 端點是否有效，或者刪掉這個 header 改走 OAuth 流程。claude -p 和 Agent SDK 執行裡沒有 /mcp 面板，需要先在互動工作階段裡（或用 claude mcp login <name>）完成登入。

超時和輸出限制

• 啟動超時用 MCP_TIMEOUT 環境變數設定，例如 MCP_TIMEOUT=10000 claude 是 10 秒。
• 給某個伺服器設定單次工具呼叫的超時：在它的 .mcp.json 條目里加一個以毫秒為單位的 timeout 欄位，例如 "timeout": 600000 是十分鐘。它只對這個伺服器覆蓋 MCP_TOOL_TIMEOUT 環境變數。
• MCP 工具輸出超過 10,000 token 時 Claude Code 會警告，預設上限是 25,000 token。要調高，在啟動 Claude Code 之前設定 MAX_MCP_OUTPUT_TOKENS：

export MAX_MCP_OUTPUT_TOKENS=50000
claude

警告閾值是固定的。成功的文字結果超過 50,000 個字元時，無論這個變數設多少，都會被儲存到檔案裡（除非伺服器自己調高了該工具的上限）。

常見問題排查

常見問題

來源

• Claude Code：Connect Claude Code to tools via MCP（claude mcp add、作用域、.mcp.json、認證、輸出限制，2026 年 10 月 30 日核對）