​
什么是 MCP？

模型上下文协议（MCP） 使 Cursor 能够连接外部工具和数据源。

​
为什么使用 MCP？

MCP 将 Cursor 连接到外部系统和数据。与其一遍遍解释你的项目结构，不如直接和你的工具集成。 用任何能向 stdout 输出或提供 HTTP 端点的语言编写 MCP 服务器——比如 Python、JavaScript、Go 等。

​
工作原理

MCP 服务器通过协议暴露能力，将 Cursor 连接到外部工具或数据源。 Cursor 支持三种传输方式：
传输方式执行环境部署用户输入认证
stdio本地由 Cursor 管理单用户Shell 命令手动
SSE本地/远程以服务器形式部署多用户指向 SSE 端点的 URLOAuth
Streamable HTTP本地/远程以服务器形式部署多用户指向 HTTP 端点的 URLOAuth

​
协议支持

Cursor 支持以下 MCP 协议能力：
功能支持情况描述
Tools已支持供 AI 模型调用执行的函数
Prompts已支持面向用户的模板化消息与工作流
Resources已支持可读取并引用的结构化数据源
Roots已支持服务器发起的对 URI 或文件系统边界的查询，用于确定操作范围
Elicitation已支持服务器发起的向用户补充信息的请求

​
安装 MCP 服务端

​
一键安装

从我们的库中安装 MCP 服务器，并通过 OAuth 完成认证。

Browse MCP Tools

浏览可用的 MCP 服务器

Add to Cursor Button

创建 “Add to Cursor” 按钮

​
使用 mcp.json

通过 JSON 文件配置自定义 MCP 服务器： 
{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

​
STDIO 服务器配置

对于 STDIO 服务器（本地命令行服务器），在你的 mcp.json 中配置以下字段：
FieldRequiredDescriptionExamples
typeYes服务器连接类型"stdio"
commandYes启动服务器可执行文件的命令。必须在系统 PATH 中可用，或包含其绝对路径。"npx", "node", "python", "docker"
argsNo传给该命令的参数数组["server.py", "--port", "3000"]
envNo服务器的环境变量{"API_KEY": "${input:api-key}"}
envFileNo用于加载更多变量的环境文件路径".env", "${workspaceFolder}/.env"

​
使用扩展 API

为了以编程方式注册 MCP 服务器，Cursor 提供了扩展 API，可在不修改 mcp.json 文件的前提下进行动态配置。这对企业环境和自动化部署流程尤其有用。

MCP 扩展 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 key 和 token 写在配置里传递。 Cursor 也支持需要 OAuth 的服务器。

​
在聊天中使用 MCP

Composer Agent 会在合适的情况下自动调用列在 Available Tools 下的 MCP 工具。可以按名称点名某个工具，或直接描述你需要的功能。你也可以在设置里启用或禁用工具。

​
切换工具

可以直接在聊天界面启用或禁用 MCP 工具。点开工具列表里的工具名就能切换。被禁用的工具不会加载到上下文里，Agent 也用不了它们。

​
工具许可

Agent 默认会在使用 MCP 工具前请求确认。点击工具名称旁的箭头即可查看参数。

​
自动运行

启用自动运行后，Agent 可以在不确认的情况下使用 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 的实际用法，看看我们的 Web Development 指南，里面演示了如何把 Linear、Figma 和浏览器工具集成到你的开发流程中。

​
常见问题

MCP 服务器把 Cursor 连接到 Google Drive、Notion 等外部工具和服务，把文档和需求直接带进你的编码流程。
这样查看 MCP 日志：1. 在 Cursor 中打开 Output 面板（Ctrl+Shift+U） 2. 在下拉菜单选择 “MCP Logs” 3. 检查连接错误、认证问题或服务器崩溃 日志会显示服务器初始化、工具调用和错误信息。
可以！不用移除就能开/关服务器：1. 打开 Settings（ Ctrl+Shift+J）2. 前往 Features → Model Context Protocol 3. 点击任一服务器旁的开关启用/禁用 被禁用的服务器不会加载，也不会出现在聊天里。适合排查问题或减少工具干扰。
如果某个 MCP 服务器失败：- Cursor 会在聊天里显示错误信息 - 工具调用会被标记为失败 - 你可以重试操作或查看日志获取详情 - 其他 MCP 服务器会照常工作 Cursor 会隔离服务器故障，避免一个服务器影响其他服务器。
对于基于 npm 的服务器：1. 在设置里移除该服务器 2. 清理 npm 缓存： npm cache clean --force 3. 重新添加该服务器以获取最新版本 对于自定义服务器，更新本地文件并重启 Cursor。
可以，但请遵循安全最佳实践：- 用环境变量存放密钥，别硬编码 - 在本地用 stdio 传输运行敏感服务器 - 将 API key 权限限制到最低必要 - 在连接敏感系统前先审查服务器代码 - 考虑在隔离环境中运行服务器