Cursor MCP 配置教學：mcp.json 寫法、項目與全局位置、OAuth 與連接失敗排查

本文根據 Cursor 官方文檔《Model Context Protocol (MCP)》整理，資料核對於 2026-10-11。MCP 本身是什麼，見本站《MCP 是什麼》。

適用於誰

• 想讓 Cursor 直接查數據庫、讀 Linear / Notion / Figma 的人；
• 搜「cursor mcp 配置」「cursor mcp 設定」「cursor mcp 使用」的人；
• 照着網上的 JSON 抄了一段，伺服器卻不出現或一直報錯的人。

結論先說

1. 兩條路：在 Cursor Marketplace 裏點「Add to Cursor」一鍵安裝（走 OAuth 登入）；或者手寫 mcp.json。
2. 配置文件兩個位置：項目裏的 .cursor/mcp.json（只對這個項目）和用戶目錄下的 ~/.cursor/mcp.json（所有項目）。
3. 本地伺服器寫 command + args；遠程伺服器寫 url。密鑰不要寫死，用 ${env:變量名} 引用環境變量。
4. 預設每次調用 MCP 工具前 Cursor 都會先問你；是否自動運行跟着運行模式（Run Mode）走。
5. 出問題先看日誌：輸出面板裏選 MCP Logs。
6. 用不到的伺服器在 Customize 裏關掉——官方說關閉後它不會加載，也能減少工具列表的干擾。

方式一：從 Marketplace 一鍵安裝

打開側邊欄的 Customize，或訪問 Cursor Marketplace，找到需要的官方插件，點 Add to Cursor，按提示在瀏覽器裏完成 OAuth 登入即可。官方說明 Marketplace 裏是官方插件；社區的插件和 MCP 伺服器可以在 cursor.directory 瀏覽——社區來源的要自己把關，見文末的安全提示。

方式二：手寫 mcp.json

本地（stdio）伺服器

由 Cursor 在你電腦上啟動一個進程：

json
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "${env:MY_API_KEY}"
      }
    }
  }
}

Python 寫的伺服器把 command 換成 python、args 寫腳本路徑即可。

遠程（HTTP / SSE）伺服器

json
{
  "mcpServers": {
    "remote-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
      }
    }
  }
}

Cursor 支持三種傳輸方式：stdio（本地、單人）、SSE 和 Streamable HTTP（本地或遠程、可多人、支持 OAuth）。

能用哪些變量

command、args、env、url、headers 裏都可以用：

• ${env:NAME}：環境變量；
• ${userHome}：用戶主目錄；
• ${workspaceFolder}：項目根目錄（即包含 .cursor/mcp.json 的那個文件夾）；
• ${workspaceFolderBasename}：項目文件夾名；
• ${pathSeparator} 或 ${/}：系統路徑分隔符。

項目配置還是全局配置

Windows 上 ~ 指 C:\Users\你的用戶名。要提交進倉庫的項目配置，更要堅持用 ${env:...}，不要把密鑰提交上去。

需要 OAuth 的伺服器

大多數遠程伺服器裝好後會自動引導你在瀏覽器登入。少數服務不支持動態註冊客戶端，或者要求把回調地址加白（官方舉例 Figma、Linear），這時在條目裏加 auth：

json
{
  "mcpServers": {
    "oauth-server": {
      "url": "https://api.example.com/mcp",
      "auth": {
        "CLIENT_ID": "${env:MCP_CLIENT_ID}",
        "CLIENT_SECRET": "${env:MCP_CLIENT_SECRET}",
        "scopes": ["read", "write"]
      }
    }
  }
}

在對方平台登記回調地址時，桌面端填 http://localhost:8787/callback，網頁端和雲端 Agent 填 https://www.cursor.com/agents/mcp/oauth/callback；兩邊都用就兩個都登記。

在對話裏使用

配置好的工具會出現在 Available Tools 裏，Agent 覺得相關就會自動調用（Plan 模式裏也會）；你也可以直接點名「用 xx 工具查一下」。

預設情況下，每次調用前會彈出確認，點工具名旁的箭頭可以先看參數：

圖片來源：Cursor 官方文檔《Model Context Protocol (MCP)》

MCP 工具和終端命令共用同一套運行模式。比如在 Auto-review 模式下，白名單裏的工具直接運行，其他的交給分類器審查。詳見《Cursor 私隱模式與 Agent 權限》。

常見問題

Q：怎麼排查連不上？

Ctrl+Shift+U（macOS Cmd+Shift+U）打開輸出面板，下拉選 MCP Logs，裏面有初始化、工具調用和報錯訊息。常見原因是 command 不在 PATH 裏（裝了 Node.js / Python 嗎）、環境變量沒設、JSON 少了逗號或引號。

Q：一個伺服器崩了會影響別的嗎？

不會。官方說明各伺服器互相隔離：出錯的那次工具調用標記為失敗，可以重試或看日誌，其他伺服器照常工作。

Q：怎麼更新 npm 裝的伺服器？

官方步驟：在 Customize 裏移除 → 運行 npm cache clean --force → 重新添加。自己寫的伺服器更新文件後重啟 Cursor。

Q：.cursorignore 能擋住 MCP 讀文件嗎？

擋不住。官方提醒：終端命令和 MCP 工具運行在 Cursor 的文件訪問控制之外，仍可能讀到被忽略的文件。

Q：能連敏感數據嗎？

可以，但官方要求：密鑰用環境變量；敏感的伺服器用 stdio 在本地跑；API Key 只給最小權限；接入重要系統前讀一遍伺服器源碼。MCP 伺服器能代你訪問外部服務、執行代碼，裝之前要弄清它做什麼。怎麼挑和審，見《MCP 伺服器怎麼選》。

參考資料

• Model Context Protocol (MCP)（Cursor 官方）：https://cursor.com/docs/mcp
• Run Modes（Cursor 官方）：https://cursor.com/docs/agent/security/run-modes
• Ignore files（Cursor 官方幫助中心）：https://cursor.com/help/customization/ignore-files
• MCP 協議介紹（官方）：https://modelcontextprotocol.io/introduction