模型上下文协议 (MCP)

什么是 MCP？

模型上下文协议 (MCP) 让 Cursor 能够连接外部工具和数据源。你可以在自定义页面安装和管理 MCP 服务器，也可以在 mcp.json 中进行配置。

为什么使用 MCP？

MCP 可将 Cursor 连接到外部系统和数据。无需反复解释项目结构，直接与工具集成即可。

可使用任何能向 stdout 输出内容或提供 HTTP 端点的语言编写 MCP 服务器，例如 Python、JavaScript、Go 等。

在插件市场浏览官方插件。社区插件和 MCP 服务器请浏览 cursor.directory。

工作原理

MCP 服务器通过该协议提供能力，让 Cursor 能够连接到外部工具或数据源。

Cursor 支持三种传输方式：

协议与扩展支持

Cursor 支持以下 MCP 协议能力和扩展：

MCP 应用

Cursor 支持 MCP Apps 扩展。MCP 工具除标准工具输出外，还可返回交互式 UI。

MCP Apps 采用渐进增强设计。即使宿主无法渲染应用 UI，同一工具仍可通过常规 MCP 响应正常运行。

安装 MCP 服务器

一键安装

在 插件市场浏览官方插件，可通过 自定义 一键安装；也可使用 mcp.json 配置自定义服务器。社区插件和 MCP 服务器请浏览 cursor.directory。在插件市场条目中点击“添加到 Cursor”即可安装，并通过 OAuth 认证。

团队管理员还可通过团队插件市场分发 MCP 服务器。团队分发的服务器会与个人和工作区 MCP 服务器一同显示在“自定义”中。

使用 mcp.json

通过 JSON 文件配置自定义 MCP 服务器：

{  "mcpServers": {    "server-name": {      "command": "npx",      "args": ["-y", "mcp-server"],      "env": {        "API_KEY": "value"      }    }  }}

{  "mcpServers": {    "server-name": {      "command": "python",      "args": ["mcp-server.py"],      "env": {        "API_KEY": "value"      }    }  }}

// 使用 HTTP 或 SSE 的 MCP 服务器 - 在远程服务器上运行{  "mcpServers": {    "server-name": {      "url": "http://localhost:3000/mcp",      "headers": {        "API_KEY": "value"      }    }  }}

远程服务器的静态 OAuth

对于使用 OAuth 的 MCP 服务器，你可以在 mcp.json 中提供静态 OAuth 客户端凭据，无需使用动态客户端注册。适用于以下情况：

• MCP 提供商为你提供固定的 Client ID (以及可选的 Client Secret)
• 提供商要求将重定向 URL 列入白名单 (例如 Figma、Linear)
• 提供商不支持 OAuth 2.0 动态客户端注册

为使用 url 的远程服务器条目添加 auth 对象：

{  "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/callbackhttp://localhost:8787/callback

• 网页端和 Cursor Agents：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}"      }    }  }}

使用环境变量配置客户端 ID 和客户端密钥，避免将其硬编码。

STDIO 服务器配置

对于 STDIO 服务器 (本地命令行服务器) ，请在 mcp.json 中配置以下字段：

使用扩展 API

如需以编程方式注册 MCP 服务器，Cursor 提供扩展 API，无需修改 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 服务器通过环境变量进行身份验证。请通过 config 传递 API 密钥和 token。

Cursor 支持 OAuth，可用于需要 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 文档
• 网页开发指南 — 将 Linear、Figma 和浏览器工具集成到开发工作流中

常见问题