Cursor MCP 配置教程：在 Cursor 中添加和配置 MCP 服务器

如何在 Cursor 中添加 MCP 服务器

在 Cursor 中添加 MCP 服务器，只需把它写进 mcp.json：~/.cursor/mcp.json 对所有项目生效，仓库里的 .cursor/mcp.json 只对当前项目生效。本地服务器用 command 和 args（stdio），远程服务器用 url（Streamable HTTP 或 SSE）。你也可以从 Cursor Marketplace 或安装链接一键安装，然后在侧边栏的 Customize 中开启或关闭。

下文所有内容都对照官方 Cursor MCP 文档核实过。如果你还没选好要接入的服务器，可以先逛逛 MCP 服务器目录。

速查表

第 1 步：选择全局还是项目作用域

Cursor 从两个位置读取 MCP 服务器：

• 主目录下的 ~/.cursor/mcp.json：放你在任何地方都想用的工具（文档服务器、浏览器、记忆服务器）。
• 项目中的 .cursor/mcp.json：放属于这个代码库的工具（它的数据库、它的 issue 跟踪系统）。把这个文件提交到仓库，队友就能拿到同一套服务器——但绝不要把密钥写在里面（见第 3 步）。

两个文件格式相同：顶层是一个 mcpServers 对象，每个键就是你在 Cursor 中看到的服务器名称。

第 2 步：添加服务器

Cursor 支持三种传输方式。根据文档，stdio 服务器由 Cursor 自己启动和管理；SSE 和 Streamable HTTP 服务器通过 URL 访问，并可以用 OAuth 认证。

本地 stdio 服务器

stdio 服务器是 Cursor 在你电脑上启动的一个程序。下面是 Playwright MCP 服务器，它让 Agent 拥有一个真实的浏览器：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Python 服务器也是同样的结构：把 command 设为 python（或 uvx），脚本或包名放进 args。stdio 可用字段有 type（"stdio"）、command（必填）、args、env 和 envFile。

远程服务器（Streamable HTTP 或 SSE）

远程服务器只需要一个 URL。Cursor 同时支持 Streamable HTTP 和较老的 SSE 传输：

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:CONTEXT7_API_KEY}"
      }
    }
  }
}

这是 Context7 MCP 服务器，它为 Agent 提供最新的库文档。很多托管服务器（例如 Notion、Linear 或 Sentry）用 OAuth 而不是请求头：只写 url 即可，服务器第一次连接时 Cursor 会打开浏览器让你登录。两种传输方式的区别见 SSE 与 Streamable HTTP。

同时配置多个服务器

每个服务器只是 mcpServers 里的一个键，所以一个文件里可以同时放本地和远程条目。通常不需要重启；如果某个服务器没出现，在 Customize 中把它关掉再打开即可。

第 3 步：不要把密钥写进 mcp.json

在已提交的 .cursor/mcp.json 里硬编码 API Key 是最常见的错误。Cursor 内置了两种规避方式。

变量插值。 Cursor 会解析 command、args、env、url 和 headers 中的变量：

例如，把 GitHub Token 作为 Bearer 请求头传给 GitHub MCP 服务器：

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${env:GITHUB_PAT}"
      }
    }
  }
}

envFile（仅 stdio）。 让本地服务器读取一个 dotenv 文件，而不是逐个列出变量：

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

记得把这个 .env 加进 .gitignore。注意 envFile 只支持 stdio 服务器；远程服务器应在 headers 中使用 ${env:...}。

静态 OAuth 客户端

如果某个远程服务器需要预先注册的 OAuth 应用（而不是动态注册），添加一个 auth 对象，包含 CLIENT_ID（必填）、CLIENT_SECRET（可选）和 scopes（可选；省略时 Cursor 会从服务器的 OAuth 元数据中自动发现）。为桌面应用注册 http://localhost:8787/callback 作为回调地址。认证流程的原理详见我们的 MCP 认证指南。

第 4 步：一键安装链接

一键安装有两条路径：

1. Cursor Marketplace。 打开 Customize 浏览市场，或在市场条目上点击 Add to Cursor。它会安装服务器并完成 OAuth 登录。
2. 安装链接。 任何人都可以按以下格式发布深度链接（文档）：

cursor://anysphere.cursor-deeplink/mcp/install?name=$NAME&config=$BASE64_ENCODED_CONFIG

config 是单个服务器对象的 base64 编码（例如 {"command":"npx","args":["-y","@playwright/mcp@latest"]}），不包括外层的 mcpServers；名称放在 name 参数里。你可以在终端里生成：

echo -n '{"command":"npx","args":["-y","@playwright/mcp@latest"]}' | base64

点击链接后 Cursor 会弹出安装提示。像对待任何要运行的代码一样对待安装链接：接受之前先解码 config，看清楚要执行的命令。

第 5 步：使用、审批和限制工具

服务器启用后，Agent 就能看到它的工具并自行决定何时调用。默认情况下，Cursor 在每次调用 MCP 工具前都会请求批准；点击工具名旁边的箭头可以查看具体参数。在 auto-review 运行模式下，白名单中的工具会立即执行，其他调用则交给 Cursor 的分类器判断。

Cursor 支持的不只是工具：prompts、resources、roots、elicitation 以及 MCP Apps 扩展（工具返回交互式 UI）都在支持列表中。

40 个工具的上限还在吗？ 旧版 Cursor 只会把前 40 个 MCP 工具发给模型，超出时会显示警告。自 2026 年 1 月起，Cursor 采用了动态上下文发现：工具描述被同步到文件中，Agent 一开始只看到工具名，需要时才加载完整 schema。Cursor 报告称，在调用了 MCP 工具的运行中，Agent 总 token 减少了约 46.9%。即便如此，服务器越少，选错工具的概率越低，所以请在 Customize 中关闭暂时不用的服务器。如果工具选择出了问题，可以参考我们的 MCP 工具发现指南。

第 6 步：在 Cursor CLI 中使用同一套服务器

Cursor CLI（agent）与编辑器使用同一份 mcp.json 配置（CLI MCP 文档）：

agent mcp list                  # configured servers and their status
agent mcp list-tools playwright # a server's tools and parameters
agent mcp login notion          # authenticate a server from mcp.json
agent mcp disable playwright    # stop loading a server

Cursor MCP 故障排查

先看日志：打开 Output 面板（macOS 上是 Cmd+Shift+U，Windows 和 Linux 上是 Ctrl+Shift+U），在下拉菜单中选择 MCP Logs。出错的服务器会在聊天中显示错误并把该工具调用标记为失败，但其他服务器会继续运行。

如果服务器行为异常而日志信息不够，可以用 MCP Inspector 在 Cursor 之外单独测试。如果在那里也失败，问题就出在服务器本身，而不是 Cursor。

安全提示

本地 MCP 服务器以你的用户权限运行，而且每个工具结果都会进入模型的上下文。只安装可信来源的服务器，优先选择官方服务器（在目录中留意带 "Official" 的条目），对任何会写入数据的工具保持审批提示开启，接入生产系统前请先阅读我们的 MCP 安全最佳实践。

下一步

• 在 MCP 服务器目录或我们的最佳 MCP 服务器清单中挑选值得添加的服务器。
• 还要配置其他客户端？参见 Claude Code MCP、VS Code MCP 配置和 Claude Desktop MCP。
• 刚接触这个协议？先从什么是 MCP 服务器开始。