cursor-relay-mcp

Un servidor MCP local construido sobre el SDK oficial @cursor/sdk. Permite que los clientes MCP deleguen una tarea acotada a un modelo de Cursor seleccionado explícitamente, manteniendo un estado de ejecución duradero y seguro frente a reinicios.

@cursor/sdk está en beta pública. Este paquete fija exactamente 1.0.28 e incluye una prueba de contrato de exportación del SDK. Consulta README.zh-CN.md para la guía completa.

Para un flujo de instalación probado de Codex Desktop en Windows, que incluye el diseño del marketplace personal, el respaldo de CLI, la compatibilidad con sandbox, la actualización de caché y una prueba de humo con Grok 4.6, consulta CODEX_INSTALL.zh-CN.md.

Inicio rápido

Requisitos: Git, Node.js >=22.13 y una cuenta de Cursor. El método de autenticación recomendado es el inicio de sesión almacenado oficial 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

Ejecuta el inicio de sesión una vez en cada equipo y cuenta de usuario del sistema operativo que inicie el servidor MCP. El SDK oficial abre el navegador predeterminado del sistema, genera una clave de API con nombre, caducidad y revocable, y la almacena en su almacén de credenciales oficial; el relay nunca lee ni devuelve el valor de la clave. Comprueba el inicio de sesión sin exponer las credenciales:

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

logged-in significa que el proceso MCP puede usar el inicio de sesión almacenado. CURSOR_API_KEY sigue siendo una alternativa opcional para la automatización, pero no la pongas en .mcp.json, en el historial del shell, en los registros ni en el repositorio. Cuando uses el inicio de sesión almacenado, omite CURSOR_API_KEY por completo en lugar de establecerla como una cadena vacía.

El flujo normal de herramientas es doctor → list_models → start_run → llamadas repetidas a wait_run hasta que terminal=true. Las ejecuciones son idempotentes, persistentes, limitadas por un tiempo de espera total y recuperables tras reiniciar el proceso.

Los valores de seguridad predeterminados son de cierre ante fallos: las ejecuciones no supervisadas requieren la lista blanca estática del espacio de trabajo. Cuando un usuario autoriza explícitamente Cursor Relay para un espacio de trabajo en la conversación actual, authorize_workspace puede emitir una capacidad de tarea exacta, de un solo uso y de cinco minutos, solo para read-only. El token nunca se persiste y está vinculado a la ruta real, la tarea, la clave de idempotencia y la tarea/sesión MCP cuando estén disponibles. De lo contrario, los permisos predeterminados son de solo lectura, el sandbox de Cursor está habilitado por defecto en hosts no Windows compatibles y solo se cargan los ajustes del proyecto. Windows desactiva el sandbox del SDK por defecto porque el runtime local actual lo reporta como no compatible; la lista blanca de herramientas de solo lectura sigue aplicándose. workspace-write aún requiere la lista blanca estática. danger-full-access requiere tanto CURSOR_RELAY_ENABLE_DANGER_FULL_ACCESS=true al iniciar el servidor como confirmedDangerousPermission=true en la solicitud. Deja el interruptor del servidor desactivado para uso normal.

CURSOR_RELAY_READ_ONLY_SANDBOX_ENABLED puede desactivar explícitamente el sandbox en hosts no Windows compatibles. Windows siempre fuerza esta configuración a desactivada porque el runtime local actual del SDK de Cursor no admite esa ruta de sandbox. Este interruptor se aplica solo al preset read-only; su lista blanca de herramientas públicas sigue restringida a read, grep, glob y ls. workspace-write aún requiere soporte de sandbox del SDK.

CURSOR_RELAY_SETTING_SOURCES es una lista opcional separada por comas restringida a las capas de ajustes públicas project, team y mdm. Su valor predeterminado es project; user, plugins y all se rechazan deliberadamente para evitar comportamientos MCP ambientales o recursivos.

Los resúmenes de ejecución omiten los eventos transmitidos e informan eventCount; usa read_events para las páginas de eventos. Los datos de eventos mayores de 8 KiB se reemplazan con metadatos de truncamiento explícitos. La redacción se basa en nombres de campos sensibles y no es un escáner general de secretos, así que usa un directorio de estado privado y evita secretos en los prompts.

El relay usa solo exportaciones públicas del SDK fijado: descubrimiento de modelos, Agent.create/resume/listRuns/getRun, Run.stream/wait/cancel y el estado de autenticación oficial. No inspecciona el estado del IDE de Cursor ni endpoints privados. No es necesario reiniciar el IDE de Cursor para ejecuciones locales del SDK.

Related MCP server: mcp-job-queue

Verificación

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

Las pruebas predeterminadas no llaman a la API real de Cursor ni modifican un espacio de trabajo real.