《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 帮助信息