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 서버를 시작하는 각 컴퓨터 및 OS 사용자 계정에서 로그인을 한 번 실행하세요. 공식 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, 셸 히스토리, 로그 또는 저장소에 넣지 마세요. 저장된 로그인을 사용할 때는 CURSOR_API_KEY를 빈 문자열로 설정하는 대신 완전히 생략하세요.

일반적인 도구 흐름은 doctor → list_models → start_run → terminal=true가 될 때까지 반복적인 wait_run 호출입니다. 실행은 멱등적이고, 지속되며, 총 시간 제한이 있고, 프로세스 재시작 후 복구 가능합니다.

보안 기본값은 실패 시 잠금(fail-closed)입니다: 무인 실행에는 정적 작업 공간 허용 목록이 필요합니다. 사용자가 현재 대화에서 특정 작업 공간에 대해 Cursor Relay를 명시적으로 승인하면, authorize_workspace는 read-only 전용의 5분, 단일 사용, 정확한 작업 기능을 발급할 수 있습니다. 토큰은 절대 지속되지 않으며 실제 경로, 작업, 멱등성 키, 그리고 가능한 경우 MCP 작업/세션에 바인딩됩니다. 권한은 기본적으로 읽기 전용으로 설정되고, 지원되는 비Windows 호스트에서는 Cursor 샌드박스가 기본적으로 활성화되며, 프로젝트 설정만 로드됩니다. 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를 사용하세요. 8KiB보다 큰 이벤트 데이터는 명시적 잘림 메타데이터로 대체됩니다. 편집은 민감한 필드 이름을 기반으로 하며 일반적인 비밀 스캐너가 아니므로, 비공개 상태 디렉토리를 사용하고 프롬프트에 비밀을 포함하지 마세요.

릴레이는 고정된 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를 호출하거나 실제 작업 공간을 수정하지 않습니다.