Claude Desktop MCP 配置教學：claude_desktop_config.json 在哪、怎麼寫、不生效怎麼查

本文根據 MCP 官方教學《Connect to local MCP servers》整理，資料核對於 2026-10-11。沒有登入帳號操作，選單名稱取自官方教學原文。Claude 桌面版的下載安裝見《Claude 桌面版》；一鍵安裝的桌面擴展和遠程連接器見《Claude 連接器》。

適用於誰

• 搜「claude desktop mcp 配置」「claude desktop 如何配置 mcp」「claude desktop mcp config file」的人；
• 某個 MCP 伺服器的 README 裏只給了一段 mcpServers 的 JSON，不知道該粘到哪的人；
• 配置寫好了，重啟後 Claude 裏卻看不到那個伺服器的人。

結論先說

1. 入口在選單欄的 Claude 選單 → Settings → Developer → Edit Config。注意是系統選單欄裏的 Claude 選單，不是對話窗口裏的帳號設定。
2. 配置文件叫 claude_desktop_config.json：macOS 在 ~/Library/Application Support/Claude/，Windows 在 %APPDATA%\Claude\。
3. 寫法是一個 mcpServers 對象，每個伺服器一項，包含 command（用什麼啟動）和 args（參數）。
4. 改完必須完全退出再重開 Claude Desktop，不是關窗口。
5. 不生效先看日誌：macOS 在 ~/Library/Logs/Claude，Windows 在 %APPDATA%\Claude\logs。

一、準備

• Claude Desktop：官方教學寫的是支持 macOS 和 Windows。已經裝了的話，在 Claude 選單裏選「Check for Updates...」確認是最新版；
• Node.js：教學用的 filesystem 伺服器以及很多其他 MCP 伺服器需要它。在終端裏運行下面的命令確認已安裝，沒有的話去 nodejs.org 下載，官方建議用 LTS 版本。

bash
node --version

二、打開配置文件

1. 點擊系統選單欄裏的 Claude 選單，選擇「Settings...」。官方特別強調不是 Claude 窗口內部的設定；
2. 在設定窗口左側選 Developer 標籤；
3. 點擊 Edit Config 按鈕。

這一步會打開配置文件；文件不存在時會新建一個。位置是：

三、寫入伺服器配置

官方教學的例子是 filesystem 伺服器，讓 Claude 能讀寫你指定的文件夾。

macOS：

json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    }
  }
}

Windows：

json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\username\\Desktop",
        "C:\\Users\\username\\Downloads"
      ]
    }
  }
}

把 username 換成你電腦的用戶名。各部分的含義：

三個寫的時候容易出錯的地方：

• Windows 路徑裏的反斜槓要寫兩個（C:\\Users\\...），這是 JSON 的轉義規則；
• 路徑必須是絕對路徑，不能用相對路徑；
• 要加第二個伺服器，是在 mcpServers 裏再加一項，用逗號隔開，而不是再寫一個 mcpServers。

官方的安全提醒：只授權你願意讓 Claude 讀取和修改的目錄。伺服器以你的用戶帳號權限運行，你能手動做的文件操作它都能做。不要圖省事把整個主目錄交出去。

四、重啟並確認

1. 儲存文件後，完全退出 Claude Desktop 再重新打開；
2. 點擊對話輸入框左下角的加號按鈕（官方教學裏叫「Add files, connectors, and more」）；
3. 把滑鼠移到 Connectors 上，點 Manage connectors；
4. 在列表裏選中 filesystem，可以看到它提供的工具。

五、試着用

官方給的幾個測試說法：

• 「寫一首詩並儲存到我的桌面」；
• 「我的下載文件夾裏有哪些和工作相關的文件？」；
• 「把桌面上的所有圖片整理到一個叫 Images 的新文件夾裏」。

每次操作前 Claude 都會請求你批准。彈出的請求仔細看一眼再同意，不放心就拒絕。

六、伺服器沒出現：五步排查

官方教學的排查順序：

1. 完全重啟 Claude Desktop；
2. 檢查 JSON 語法。多一個逗號、少一個引號都會讓整個文件失效；
3. 檢查路徑：配置裏的路徑是否存在，是否為絕對路徑；
4. 看日誌（位置見下一節）；
5. 在終端裏手動運行一遍伺服器，看有沒有報錯：

bash
npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop /Users/username/Downloads

Windows 上把路徑換成 C:\Users\username\Desktop 這樣的寫法。手動運行都起不來的話，問題在伺服器或 Node.js 環境，而不在 Claude。

七、日誌在哪

• mcp.log：MCP 連接和連接失敗的總體日誌；
• mcp-server-伺服器名.log：對應伺服器的標準錯誤輸出。官方說明 stdio 伺服器可能把所有日誌都寫到標準錯誤，所以這個文件裏的內容不一定都是錯誤。

查看最近的日誌並持續跟蹤（macOS / Linux）：

bash
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Windows（只顯示最近的日誌）：

powershell
type "%APPDATA%\Claude\logs\mcp*.log"

八、Windows 上的 ENOENT 與 ${APPDATA} 報錯

官方教學專門列了這個問題：伺服器加載失敗，日誌裏出現路徑中帶 ${APPDATA} 的報錯。解決辦法是在該伺服器的配置裏加上 env，把 %APPDATA% 展開後的實際值寫進去，形如：

json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\username\\Desktop"],
      "env": {
        "APPDATA": "C:\\Users\\username\\AppData\\Roaming\\"
      }
    }
  }
}

改完重新啟動 Claude Desktop。

官方還提醒：如果 npm 沒有全局安裝，npx 可能仍然失敗。全局安裝過的話，系統裏會有 %APPDATA%\npm 這個目錄；沒有的話運行：

bash
npm install -g npm

九、工具調用悄悄失敗

Claude 嘗試使用工具但沒有成功時，官方給的三步：看 Claude 的日誌裏有沒有報錯；確認伺服器能正常構建和運行；重啟 Claude Desktop。

還不行的話，用 MCP 官方的調試工具單獨連這個伺服器，排除 Claude 這一側的因素，見《MCP Inspector 怎麼用》。

常見問題

Q：需要密鑰的伺服器怎麼配？

在該伺服器的配置裏加 env 對象，把密鑰作為環境變量傳入，變量名按那個伺服器的 README 來。配置文件裏有密鑰時，注意不要把它同步到網盤或發給別人。

Q：這和「連接器」「桌面擴展」是什麼關係？

三種都是讓 Claude 用上 MCP 的方式。連接器是遠程服務，在介面裏點幾下登入即可；桌面擴展是打包好的本地伺服器，一鍵安裝；手動編輯配置文件最靈活，任何提供了 mcpServers 寫法的伺服器都能配，也最需要自己把關。

Q：這份配置能給 Claude Code 用嗎？

兩者的配置文件不是同一個。Claude Code 用 claude mcp add 命令或項目裏的 .mcp.json，見《Claude Code MCP 配置教學》。mcpServers 裏每一項的寫法是相通的。

Q：能裝哪些伺服器、怎麼判斷靠不靠譜？

本地 MCP 伺服器是以你的身份運行的程序，先審再裝，見《MCP 伺服器怎麼選、裝之前怎麼審》。本地和遠程的區別見《MCP 的 stdio、SSE 和 Streamable HTTP 有什麼區別》。

參考資料

• Connect to local MCP servers（MCP 官方教學）：https://modelcontextprotocol.io/docs/develop/connect-local-servers