《Cursor文檔》-模型上下文協議 (MCP)

什麼是 MCP？¶

模型上下文協議 (MCP) 讓 Cursor 能夠連接外部工具和數據源。你可以在自定義頁面安裝和管理 MCP 服務器，也可以在 mcp.json 中進行配置。

爲什麼使用 MCP？¶

MCP 可將 Cursor 連接到外部系統和數據。無需反覆解釋您的項目結構，直接與您的工具集成即可。

您可以使用任何能夠輸出到 stdout 或提供 HTTP 端點的語言來編寫 MCP 服務器，例如 Python、JavaScript、Go 等。

在 Cursor Marketplace 瀏覽官方插件。社區插件和 MCP 服務器請瀏覽 cursor.directory。

工作原理¶

MCP 服務器通過該協議提供能力，將 Cursor 連接到外部工具或數據源。

Cursor 支持三種傳輸方式：

協議和擴展支持¶

Cursor 支持以下 MCP 協議能力和擴展：

MCP 應用¶

Cursor 支持 MCP 應用擴展。MCP 工具除了標準工具輸出外，還可以返回交互式 UI。

MCP 應用遵循漸進增強原則。如果宿主無法渲染應用 UI，同一個工具仍然可以通過常規的 MCP 響應正常工作。

安裝 MCP 服務器¶

一鍵安裝¶

在 插件市場瀏覽官方插件，可通過 自定義 一鍵安裝；也可使用 mcp.json 配置自定義服務器。社區插件和 MCP 服務器請瀏覽 cursor.directory。在插件市場條目中點擊“添加到 Cursor”即可安裝，並通過 OAuth 認證。

團隊管理員還可通過團隊插件市場分發 MCP 服務器。團隊分發的服務器會與個人和工作區 MCP 服務器一同顯示在“自定義”中。

使用 mcp.json¶

通過 JSON 文件配置自定義 MCP 服務器：
```json title=”CLI Server - Node.js”
{
“mcpServers”: {
“server-name”: {
“command”: “npx”,
“args”: [“-y”, “mcp-server”],
“env”: {
“API_KEY”: “value”
}
}
}
}

```json title="CLI Server - Python"
{
  "mcpServers": {
    "server-name": {
      "command": "python",
      "args": ["mcp-server.py"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

```json title=”Remote Server”
// MCP server using HTTP or SSE - runs on a server
{
“mcpServers”: {
“server-name”: {
“url”: “http://localhost:3000/mcp”,
“headers”: {
“API_KEY”: “value”
}
}
}
}

### 遠程服務器的靜態 OAuth

對於使用 OAuth 的 MCP 服務器，你可以在 `mcp.json` 中提供**靜態 OAuth 客戶端憑據**，而不使用動態客戶端註冊。適用於以下情況：

- MCP 提供方爲你提供固定的**客戶端 ID** (以及可選的**客戶端密鑰**)
- 提供方要求**將重定向 URL 列入白名單** (例如 Figma、Linear)
- 提供方不支持 OAuth 2.0 動態客戶端註冊

爲使用 `url` 的遠程服務器條目添加一個 `auth` 對象：
```json title="Remote Server with Static OAuth"
{
  "mcpServers": {
    "oauth-server": {
      "url": "https://api.example.com/mcp",
      "auth": {
        "CLIENT_ID": "your-oauth-client-id",
        "CLIENT_SECRET": "your-client-secret",
        "scopes": ["read", "write"]
      }
    }
  }
}

固定重定向 URL¶

Cursor 對 MCP 服務器使用固定的 OAuth 重定向 URL。請爲用戶進行認證時所用的每個來源界面註冊回調：

https://www.cursor.com/agents/mcp/oauth/callback
http://localhost:8787/callback

• 網頁端和 Cursor 代理: https://www.cursor.com/agents/mcp/oauth/callback
• 桌面應用: http://localhost:8787/callback

配置 MCP 提供方的 OAuth 應用時，如果用戶既會通過網頁端認證，也會通過桌面端認證，請將這兩個 URL 都註冊爲允許的重定向 URI。服務器通過 OAuth state 參數識別，因此這些重定向 URL 適用於所有 MCP 服務器。

與配置插值結合使用¶

auth 值支持與其他字段相同的插值方式：

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

使用環境變量設置 Client ID 和 Client Secret，不要將其硬編碼在代碼中。

STDIO 服務器配置¶

對於 STDIO 服務器 (本地命令行服務器) ，請在 mcp.json 中配置以下字段：

envFile 選項僅適用於 STDIO 服務器。遠程服務器 (HTTP/SSE) 不支持 envFile。對於遠程服務器，請改用 配置插值，並在 shell 配置文件或系統環境中設置環境變量。

使用擴展 API¶

對於以編程方式註冊 MCP 服務器，Cursor 提供了擴展 API，無需修改 mcp.json 文件即可進行動態配置。這對於企業環境和自動化設置工作流尤其有用。

擴展 API 參考¶

使用
vscode.cursor.mcp.registerServer()
以編程方式註冊 MCP 服務器

配置位置¶

項目配置¶

在項目中創建 .cursor/mcp.json，用於項目專屬工具。

全局配置¶

在主目錄中創建 ~/.cursor/mcp.json，用於在任何地方都可用的工具。

配置插值¶

在 mcp.json 的值中使用變量。Cursor 會解析這些字段中的變量：command、args、env、url 和 headers。

支持的語法：

• ${env:NAME} 環境變量
• ${userHome} 主目錄路徑
• ${workspaceFolder} 項目根目錄 (包含 .cursor/mcp.json 的文件夾)
• ${workspaceFolderBasename} 項目根目錄名稱
• ${pathSeparator} 和 ${/} 操作系統路徑分隔符

示例

{
  "mcpServers": {
    "local-server": {
      "command": "python",
      "args": ["${workspaceFolder}/tools/mcp_server.py"],
      "env": {
        "API_KEY": "${env:API_KEY}"
      }
    }
  }
}

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

身份驗證¶

MCP 服務器使用環境變量進行身份驗證。請通過配置傳遞 API 密鑰和 token。

Cursor 支持需要 OAuth 的服務器。

企業版管理員控制項¶

MCP 分發和 MCP 策略需分別配置。團隊管理員可以分發共享的 MCP 服務器。企業版管理員可以配置 MCP 策略。

團隊 MCP 分發¶

在 儀表盤 > 集成與 MCP 中配置共享的團隊 MCP 服務器。這些服務器可供雲端代理使用。

如需讓現有的獨立團隊 MCP 服務器在代理窗口、IDE 和 CLI 中可用，請在 團隊 MCP 服務器 下選擇 添加到團隊插件市場。Cursor 會將該服務器關聯到默認團隊插件市場，不會中斷雲端代理的訪問。隨後，團隊成員可在“自定義”中安裝和配置該服務器。

將 MCP 服務器關聯到插件市場並不會爲所有人安裝或啓用它。請在 儀表盤 > 插件 中配置 插件市場訪問權限 和插件安裝模式。完整流程請參閱遷移現有團隊 MCP。

MCP 允許列表¶

企業版管理員可以在 Cursor 儀表盤中控制用戶可運行哪些 MCP 服務器。打開 團隊設置 > MCP 配置，配置團隊可運行哪些服務器和工具。加入允許列表會批准某個 MCP 配置。它不會分發或安裝服務器。

使用 MCP 允許列表來指定已獲准的服務器：

• 命令條目 按命令模式批准本地 stdio MCP 服務器。
• URL 條目 按 URL 條目模式批准遠程 HTTP/SSE MCP 服務器。
• 工具允許列表 用於限制已獲准服務器中的哪些工具可以自動運行。將工具允許列表留空，即可允許該服務器中的所有工具自動運行。

網絡控制¶

遠程 MCP URL 受限於已配置的 URL 條目模式。

本地基於命令的 MCP 服務器使用各自的服務器級網絡模式：

• 全部允許：允許出站網絡訪問。
• 允許列表：僅允許訪問列出的目標。
• 全部拒絕：阻止出站網絡訪問。
• 無沙盒：運行時不啓用命令或網絡沙盒。

用戶 MCP 擴展¶

管理員可以允許用戶在管理員定義的命令或 URL 模式之外，自行配置 MCP 服務器。對於不符合管理員定義模式的用戶 MCP，可通過“用戶 MCP 網絡拒絕名單”阻止其訪問匹配的網絡目標。

在聊天中使用 MCP¶

Cursor 會在適當時自動使用 Available Tools 中列出的 MCP 工具，其中包括 Plan 模式。你可以按名稱指定工具，或說明你的需求。可在側邊欄的 自定義 中啓用或禁用 MCP 服務器。

工具批准¶

默認情況下，Cursor 在使用 MCP 工具前會請求批准。點擊工具名稱旁的箭頭可查看參數。

運行模式¶

MCP 採用與終端命令相同的運行模式。例如，在 Auto-review 模式下，允許列表中的 MCP 工具會立即運行，其餘內容則會交由分類器處理。

工具響應¶

Cursor 會在聊天中顯示響應，並提供可展開的參數和響應視圖：

將圖像作爲上下文¶

MCP 服務器可以返回圖像 (如截圖、圖表等) 。請將其作爲 base64 編碼的字符串返回：

const RED_CIRCLE_BASE64 = "/9j/4AAQSkZJRgABAgEASABIAAD/2w...";
// ^ 完整 base64 已截斷以便閱讀

server.tool("generate_image", async (params) => {
  return {
    content: [
      {
        type: "image",
        data: RED_CIRCLE_BASE64,
        mimeType: "image/jpeg",
      },
    ],
  };
});

有關實現細節，請參見這個示例服務器。Cursor 會將返回的圖像附加到聊天中。如果模型支持圖像，它就會對這些圖像進行分析。

安全注意事項¶

安裝 MCP 服務器時，請注意以下安全做法：

• 驗證來源：僅從受信任的開發者和倉庫安裝 MCP 服務器
• 評審權限：檢查服務器會訪問哪些數據和 API
• 限制 API 密鑰：使用受限且僅包含最低所需權限的 API 密鑰
• 審計代碼：對於關鍵集成，請評審服務器的源代碼

請記住，MCP 服務器可以訪問外部服務，並替您執行代碼。安裝前務必先了解服務器的功能。

真實示例¶

查看 MCP 的實際應用示例：

• Xcode 集成 — 將 Cursor 連接到 Xcode 26.3+，用於構建、測試、SwiftUI 預覽和 Apple 文檔搜索
• Web 開發指南 — 將 Linear、Figma 和瀏覽器工具集成到你的開發工作流

常見問題¶

MCP 服務器有什麼用？¶

MCP 服務器可將 Cursor 連接到 Google Drive、Notion 等外部工具和服務，
把文檔和需求納入你的編碼工作流。

如何排查 MCP 服務器問題？¶

查看 MCP 日誌：

1. 在 Cursor 中打開“輸出”面板 (Cmd+Shift+U)
2. 在下拉菜單中選擇“MCP Logs”
3. 檢查是否存在連接錯誤、身份驗證問題或服務器崩潰

日誌會顯示服務器初始化、工具調用和錯誤消息。

能否臨時禁用 MCP 服務器？¶

可以！無需移除服務器，即可將其開啓或關閉：

1. 在側邊欄中打開 自定義
2. 找到要更改的 MCP 服務器
3. 使用開關將其啓用或禁用

禁用的服務器不會加載，也不會顯示在聊天中。這有助於疑難排查或減少工具干擾。

MCP 服務器崩潰或超時時會發生什麼？¶

如果 MCP 服務器發生故障：

• Cursor 會在聊天中顯示錯誤消息
• 工具調用會被標記爲失敗
• 你可以重試操作或查看日誌瞭解詳情
• 其他 MCP 服務器會繼續正常工作

Cursor 會隔離服務器故障，防止一臺服務器影響其他服務器。

如何更新 MCP 服務器？¶

對於基於 npm 的服務器：

1. 從 自定義 中移除該服務器
2. 清除 npm 緩存：npm cache clean --force
3. 重新添加該服務器以獲取最新版本

對於自定義服務器，請更新本地文件並重新啓動 Cursor。

可以將 MCP 服務器用於敏感數據嗎？¶

可以，但請遵循安全最佳實踐：

• 使用環境變量存儲機密信息，切勿硬編碼
• 使用 stdio 傳輸方式在本地運行處理敏感數據的服務器
• 將 API 密鑰權限限制在最低必要範圍內
• 連接敏感系統前，審查服務器代碼
• 考慮在隔離環境中運行服務器

相關內容¶

• MCP 幫助信息