cursor-relay-mcp

一个基于官方 @cursor/sdk 构建的本地 MCP 服务器。它允许 MCP 客户端将有限任务委托给显式选择的 Cursor 模型，同时保持持久、可重启安全的运行状态。

@cursor/sdk 处于公开测试阶段。本包精确锁定 1.0.28 版本，并包含 SDK 导出契约测试。完整指南请参阅 README.zh-CN.md。

有关在 Windows 上经过测试的 Codex Desktop 安装流程，包括个人市场布局、CLI 回退、沙箱兼容性、缓存刷新以及 Grok 4.6 冒烟测试，请参阅 CODEX_INSTALL.zh-CN.md。

快速开始

要求：Git、Node.js >=22.13 以及 Cursor 账户。推荐的认证方式是官方 Cursor.auth.login() 存储登录。

git clone https://github.com/tonytanglab/cursor-relay-mcp.git
cd cursor-relay-mcp
npm install

# Opens the system default browser and stores an official SDK login for this OS user.
node --input-type=module --eval 'import { Cursor } from "@cursor/sdk"; await Cursor.auth.login({ apiKeyName: "cursor-relay-mcp" })'

npm run build
$env:CURSOR_RELAY_WORKSPACE_ROOTS = "D:\app\git"
node .\dist\index.js

在每台启动 MCP 服务器的计算机和操作系统用户账户上各运行一次登录。官方 SDK 会打开系统默认浏览器，生成一个具名、可过期且可撤销的 API 密钥，并将其存储在官方凭据存储中；中继器从不读取或返回密钥值。在不暴露凭据的情况下检查登录状态：

node --input-type=module --eval 'import { Cursor } from "@cursor/sdk"; console.log((await Cursor.auth.status()).status)'

logged-in 表示 MCP 进程可以使用存储的登录。CURSOR_API_KEY 仍是自动化场景的可选替代方案，但不要将其放入 .mcp.json、shell 历史、日志或仓库中。使用存储登录时，应完全省略 CURSOR_API_KEY，而不是将其设置为空字符串。

正常的工具流程是 doctor → list_models → start_run → 重复调用 wait_run 直到 terminal=true。运行是幂等的、持久的、受总超时限制的，并且可以在进程重启后恢复。

安全默认值为故障关闭（fail-closed）：无人值守运行需要静态工作区白名单。当用户在当前对话中显式授权 Cursor Relay 访问某个工作区时，authorize_workspace 可以签发一个五分钟、单次使用、精确任务的 read-only 能力。该令牌从不持久化，并绑定到真实路径、任务、幂等键以及可用的 MCP 任务/会话。其他情况下权限默认只读，Cursor 沙箱在受支持的非 Windows 主机上默认启用，且仅加载项目设置。Windows 默认关闭 SDK 沙箱，因为当前本地运行时报告其不受支持；只读工具白名单仍然强制执行。workspace-write 仍然需要静态白名单。danger-full-access 需要服务器启动时设置 CURSOR_RELAY_ENABLE_DANGER_FULL_ACCESS=true 以及请求中携带 confirmedDangerousPermission=true。正常使用时应保持服务器开关关闭。

CURSOR_RELAY_READ_ONLY_SANDBOX_ENABLED 可以在受支持的非 Windows 主机上显式禁用沙箱。Windows 始终强制关闭此设置，因为当前 Cursor SDK 本地运行时不支持该沙箱路径。此开关仅适用于 read-only 预设；其公开工具白名单仍仅限于 read、grep、glob 和 ls。workspace-write 仍然需要 SDK 沙箱支持。

CURSOR_RELAY_SETTING_SOURCES 是一个可选的逗号分隔列表，仅限于公开的 project、team 和 mdm 设置层。默认值为 project；user、plugins 和 all 被有意拒绝，以避免环境性或递归的 MCP 行为。

运行摘要省略流式事件并报告 eventCount；请使用 read_events 获取事件分页。大于 8 KiB 的事件数据会被替换为显式的截断元数据。脱敏基于敏感字段名，并非通用的密钥扫描器，因此请使用私有状态目录，并避免在提示词中包含密钥。

中继器仅使用锁定 SDK 的公开导出：模型发现、Agent.create/resume/listRuns/getRun、Run.stream/wait/cancel 以及官方认证状态。它不检查 Cursor IDE 状态或私有端点。本地 SDK 运行无需重启 Cursor IDE。

Related MCP server: mcp-job-queue

验证

npm run format:check
npm run lint
npm run typecheck
npm test
npm run build
npm run test:mcp
npm run check:package
npm run test:sdk-contract

默认测试不会调用真实的 Cursor API，也不会修改真实的工作区。