註冊
Claude

Claude Code MCP 配置教學：claude mcp add、配置文件位置與常用 MCP

一篇講清 Claude Code 怎麼接 MCP 伺服器：claude mcp add 三種寫法（HTTP / 本地 stdio / JSON）、local / project / user 三種範圍、配置文件在哪、OAuth 登入，以及連不上、超時的排查。

NNathaniel bigo··原創首發·AI 輔助撰寫
10 分鐘讀完
資料核對於 2026-10-07 · 依據官方文檔與公開資料整理 Plus 帳號
本文根據 Claude Code 官方文檔《Connect to MCP servers》《Connect Claude Code to tools via MCP》整理，核對日期 2026-10-07。文中的伺服器地址是官方文檔舉的例子，第三方服務的地址和授權方式以各服務自己的文檔為準。

適用於誰

  • 想讓 Claude Code 直接讀 GitHub PR、查數據庫、看 Sentry 報錯、操作 Notion 的人；
  • 搜「claude code mcp 配置」「mcp 配置文件位置」「mcp add global」，照着網上的 JSON 配了卻不生效的人；
  • 遇到 MCP「Failed to connect」「timed out」不知道怎麼查的人。

MCP 本身是什麼，詳見本站《MCP 是什麼：Model Context Protocol 入門，以及在 Claude 裏怎麼用》。

結論先說

  1. 在終端裏（不是在 claude 會話裏）運行 claude mcp add 添加伺服器，然後在會話裏用 /mcp 查看狀態、登入授權。
  2. 遠程伺服器用 --transport http（官方推薦）；本地程序用 stdio，伺服器自己的命令要放在 -- 後面。
  3. 預設是 local 範圍（只對你、只在當前項目）。想所有項目都能用加 --scope user；想提交給團隊用加 --scope project，會寫進項目根目錄的 .mcp.json。
  4. 配置文件只有兩個：~/.claude.json（local 和 user 範圍）和項目根目錄的 .mcp.json（project 範圍）。網上流傳的 ~/.claude/mcp.json 等路徑 Claude Code 都不讀。
  5. 每個連接的伺服器都會佔用上下文（工具名和說明每次都會加載），不用的及時刪掉。

步驟一：加一個不需要登入的伺服器試手

官方用的例子是 Claude Code 文檔搜尋伺服器，無需授權：

bash
claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp
  • claude-code-docs 是你自己起的名字，後面刪除、查看都用它；
  • 成功後會打印 Added HTTP MCP server ... to local config 和被修改的配置文件路徑。

檢查連接：

bash
claude mcp list
狀態含義
✔ Connected可以用了
! Connected · tools fetch failed連上了但拿不到工具列表，用 claude mcp get 名字 看詳情
! Needs authentication需要瀏覽器登入或在 --header 裏帶令牌
✘ Failed to connect / ✘ Connection error沒連上，見文末排查
⏸ Pending approval項目範圍的伺服器還沒被你批准，啟動 claude 時會詢問

然後啟動 claude，說「用 claude-code-docs 伺服器查一下 MCP_TIMEOUT 是做什麼的」。第一次調用會問權限，批准即可。平時不用點名，Claude 會自己挑合適的工具。

步驟二：三種添加方式

1. 遠程 HTTP 伺服器（推薦）

bash
# 基本格式
claude mcp add --transport http <名字> <地址>

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

# 需要令牌的伺服器，用 --header 傳
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer 你的令牌"

SSE 傳輸方式官方已標為棄用。只有 SSE 的老服務，新版本用同一條 --transport http 命令即可，Claude Code 會自動退回 SSE；老版本用 --transport sse。

2. 本地 stdio 伺服器

bash
# 基本格式：-- 後面是啟動伺服器的命令
claude mcp add [選項] <名字> -- <命令> [參數...]

# 官方示例：Airtable，用 --env 傳環境變量
claude mcp add --env AIRTABLE_API_KEY=你的KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

兩個易錯點：

  • -- 不能省。沒有它，Claude Code 會把伺服器自己的參數（比如 --port）當成自己的選項來解析。
  • --env 後面緊跟伺服器名字會被當成另一對 KEY=value，所以在 --env 和名字之間至少隔一個別的選項（如 --transport stdio）。

3. 直接給一段 JSON

伺服器文檔給的是 JSON 配置時：

bash
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

注意 JSON 裏有 url 就必須寫 type（http、sse 或 ws），否則會被當成 stdio 伺服器並報錯跳過。

已經在 Claude Desktop 裏配好的伺服器，可以用 claude mcp add-from-claude-desktop 導入（官方說明只支持 macOS 和 WSL）。

步驟三：選對範圍、找到配置文件

範圍生效範圍是否共享儲存位置
local（預設）只在當前項目、只對你否~/.claude.json 裏該項目的條目下
project當前項目所有人是，隨倉庫提交項目根目錄 .mcp.json
user你的所有項目否~/.claude.json 頂層的 mcpServers
bash
# 所有項目都能用（常被搜成「mcp add global」）
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

# 共享給團隊
claude mcp add --transport http shared-server --scope project https://example.com/mcp

Windows 上 ~/.claude.json 指的是 %USERPROFILE%\.claude.json，一般是 C:\Users\你的用戶名\.claude.json。範圍在添加時就定了，想改範圍要先 claude mcp remove 再用新範圍重新添加。同名伺服器出現在多個範圍時，優先級是 local > project > user > 插件 > claude.ai 連接器。

.mcp.json 示例（支持 ${變量} 和 ${變量:-預設值}，方便團隊共享又不把密鑰寫死）：

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

出於安全考慮，.mcp.json 裏的項目級伺服器第一次使用前會彈窗請你批准；想重置這些選擇，運行 claude mcp reset-project-choices。另外，ANTHROPIC_API_KEY 這類 Claude Code 自身的憑據變量在遠程伺服器的 url / headers 裏會被讀成空值，防止項目配置把你的憑據發給第三方。

步驟四：需要登入的伺服器（OAuth）

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

然後在會話裏輸入 /mcp，選中伺服器，按提示在瀏覽器裏登入。令牌會安全儲存並自動刷新；想撤銷，在 /mcp 選單裏選「Clear authentication」。也可以不進會話直接在終端裏登入：claude mcp login sentry（SSH 等沒有瀏覽器的環境會打印授權連結，加 --no-browser 可強制這樣做）。

用令牌而不是 OAuth 的服務（比如官方舉例的 GitHub MCP）：

bash
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer 你的GitHub令牌"

claude mcp add 不校驗令牌，填錯也會儲存成功，要用 /mcp 確認狀態是 connected。

如果你用 claude.ai 帳號登入 Claude Code，在 claude.ai「連接器」裏添加過的伺服器會自動出現在 Claude Code 裏。

常用管理命令

bash
claude mcp list                 # 列出所有伺服器及狀態
claude mcp get 名字              # 查看某個伺服器的詳情和所在範圍
claude mcp remove 名字           # 刪除（同時清除儲存的授權）
claude mcp reset-project-choices  # 重置對 .mcp.json 伺服器的批准

會話裏：/mcp 打開管理面板；/mcp reconnect all 重連所有失敗的伺服器；/mcp disable 名字 暫時停用而不刪除。

權限上，MCP 工具名的格式是 mcp__伺服器名__工具名，可以在權限規則裏寫 mcp__github 放行或禁止某個伺服器的全部工具，詳見本站《Claude Code 權限模式詳解：auto、手動、plan、bypass 與權限規則配置》。

常見問題

Q：/mcp 顯示「No MCP servers configured」？

最常見三種原因：一是你在別的項目目錄裏加的（local 範圍只認添加時的項目，換用 --scope user）；二是手動改錯了文件路徑（只認 ~/.claude.json 和項目根的 .mcp.json）；三是 .mcp.json 裏有格式錯誤的條目被跳過了，claude mcp list 會給出解析警告。

Q：Failed to connect 怎麼查？

先看 claude mcp get 名字 輸出的 HTTP 狀態碼。遠程伺服器可以 curl -I 地址 測試（PowerShell 裏要用 curl.exe）：返回 404 / 405 說明伺服器在線（很多 MCP 端點只接受 POST）；401 / 403 說明需要登入或令牌；完全沒響應就檢查地址和網絡。本地伺服器直接在終端裏運行那條啟動命令，看報錯缺什麼（Node.js、瀏覽器等）。

Q：啟動時超時（Connection timed out）？

預設啟動超時是 30 秒，npx 第一次下載包可能更慢。用環境變量加長：MCP_TIMEOUT=60000 claude；PowerShell 寫成 $env:MCP_TIMEOUT = "60000"; claude。單個工具調用的超時可以在 .mcp.json 條目裏加 "timeout": 600000（毫秒）。

Q：工具輸出太長被截斷？

單次 MCP 工具輸出超過 1 萬 token 會警告，預設上限 2.5 萬 token，可以用 MAX_MCP_OUTPUT_TOKENS=50000 調高。

Q：改了 .mcp.json 不生效？

.mcp.json 在會話啟動時讀取，改完要退出重開；之前拒絕過的伺服器要先 claude mcp reset-project-choices。

Q：提示「already exists」？

同一範圍裏已經有這個名字，先 claude mcp remove 名字（多個範圍都有時加 --scope local 等指定刪哪個）再重新添加，或者換個名字。

參考資料

  • Connect to MCP servers（官方快速開始）：https://code.claude.com/docs/en/mcp-quickstart
  • Connect Claude Code to tools via MCP（官方）：https://code.claude.com/docs/en/mcp
  • Environment variables（官方）：https://code.claude.com/docs/en/env-vars
  • Configure permissions（官方）：https://code.claude.com/docs/en/permissions
需要開通或續費？Claude Pro 充值 →

Nathaniel 的更多內容

  1. 01

    AI 學習路線：零基礎從哪開始，6 個階段、每階段該讀哪幾篇教學（2026）

    AI 學習路線怎麼走？給零基礎的人一條循序漸進的路徑：先選一個助手用順，再學提問，再用進日常工作，按需學做圖做影片，守住私隱與版權，最後進階自動化和編程。每個階段都配了本站對應的教學。

    其他 AI 工具0
  2. 02

    AI 瀏覽器有哪些：Perplexity Comet、Opera Neon、Dia、Brave Leo 與 Edge Copilot 的官方說法對照

    AI 瀏覽器有哪些？按官方頁面整理 Perplexity Comet、Opera Neon、Dia、Brave Leo 和 Edge 裏的 Copilot：官方自述的定位、支持的平台、免費還是訂閱，以及 Gemini、Claude 的 Chrome 方案和已停用的 ChatGPT Atlas。

    其他 AI 工具0
  3. 03

    即夢國際版 Dreamina 是什麼：官方站入口、能生成什麼、免費積分和模型（2026）

    即夢國際版 Dreamina 是什麼？官方站是 dreamina.capcut.com，是一個圖片、影片和數字人一體的 AI 創作平台。按官方首頁和 FAQ 講：能生成什麼、免費用戶每天 120 積分、列出的 Seedance 與 Seedream 模型，以及和國內即夢怎麼區分。

    其他 AI 工具0
  4. 04

    Kimi K3 Coding Plan 是什麼、怎麼用：Kimi Code 會員、模型 ID、套餐價格和額度規則

    Kimi K3 Coding Plan 是什麼？按 Kimi 官方文檔核對：官方現在叫 Kimi Code，是 Kimi 會員權益裏的編程服務，Plus 及以上才有；講 K3 等模型 ID、國內新套餐價格、三種客戶端、第三方工具接入和額度規則。

    Kimi0
  5. 05

    DeepSeek V4 Pro 和 Flash 的區別與 API 價格：官方價格頁逐項對照（高峰與空閒時段）

    DeepSeek V4 Pro 和 Flash 有什麼區別、API 怎麼收費？按 DeepSeek 官方價格頁（2026-10-19 查詢）列出兩個模型的版本、上下文、圖像理解、並發和每百萬 token 價格，說明高峰與空閒時段的計費差別和舊模型名怎麼處理。

    其他 AI 工具0
  6. 06

    GPT-6 Pro（Astra）怎麼用、哪些套餐有：怎麼選到 Pro 檔、用量限制和 Pro 三檔價格

    GPT-6 Pro（Astra）怎麼用、哪些套餐有？按 OpenAI 幫助中心核對：聊天裏 Pro 檔給 Pro 100、Pro 200、Business 和 Enterprise；Plus 在 Work 和 Codex 裏含 Astra。講怎麼選到、用量上限和官方 Pro 價格。

    ChatGPT0

同產品的其他教學

  1. 01

    Claude Pro 和 Max 的區別：用量、價格、Fable 模型和每月 API 額度怎麼選

    Claude Pro 和 Max 有什麼區別？按官方定價頁和幫助中心核對：Max 有 5x、20x 兩檔用量，Pro 與 Max 在價格、Fable 模型、每月 API 額度和計費週期上的差別，以及什麼情況下 Pro 夠用、什麼情況下該升 Max。

    Claude0
  2. 02

    Claude 登入不了、用不了、打不開怎麼辦：按官方幫助中心逐條排查

    Claude 無法登入、無法使用、無法打開怎麼辦？按官方幫助中心的順序排查：收不到登入電郵、登入報錯、Google 登入出問題、系統繁忙、額度用完、官方故障，以及所在地區是否在官方支持名單裏。

    Claude0
  3. 03

    Claude 怎麼註冊：官方註冊流程、手機驗證要求，以及提示無法註冊時官方怎麼說

    Claude 怎麼註冊？打開 claude.ai，用 Google 或電郵登入連結創建帳號，再用支持地區的手機號收短訊驗證碼。講清官方的註冊條件、手機驗證的限制，以及收不到驗證碼、號碼被用過多次時官方的處理辦法。

    Claude0
  4. 04

    Claude 怎麼用：新手入門，從打開聊天到寫出第一個好問題

    Claude 怎麼用？按官方幫助中心整理的新手路徑：在網頁、桌面版或手機 App 打開聊天，像對同事一樣寫需求，用輸入框的「+」和「/」找功能，點模型名換模型，免費版有每 5 小時重置的上限。

    Claude0
  5. 05

    Claude 怎麼設定成中文：介面語言、回答語言和語音語言分別怎麼設

    Claude 怎麼設定中文？官方幫助中心列出的 11 種介面語言裏目前沒有中文，但 Claude 會用你提問的語言回答，直接用中文問即可；想固定用中文，可在設定的 Instructions for Claude 裏寫一句。語音模式的語言要單獨選。

    Claude0
  6. 06

    MCP Inspector 怎麼用：安裝、啟動命令、調試 MCP 伺服器與 v2 的變化

    MCP Inspector 是什麼、怎麼安裝和使用？按 MCP 官方文檔講清網頁、命令行、終端介面三種模式的啟動命令，怎麼連本地和遠程伺服器、怎麼傳環境變量，密鑰存在哪，以及 v2 相比舊教學在端口、令牌變量名和 Node 版本上的變化。

    Claude其他 AI 工具0

0 條評論

登入 後參與評論

還沒有評論，來搶沙發～