Cursor Agent Gateway

OpenAI 호환 API 게이트웨이로, 공식 cursor agent CLI를 HTTP API로 래핑합니다.

개요

Cursor의 공식 CLI 도구인 cursor agent를 OpenAI 호환 REST API로 변환하여, OpenCode 등 OpenAI API를 지원하는 도구에서 Cursor의 AI 모델을 사용할 수 있게 합니다.

┌──────────────┐     HTTP      ┌─────────────────────┐     CLI      ┌──────────────┐
│   OpenCode   │ ───────────▶  │ cursor-agent-gateway │ ──────────▶ │ cursor agent │
│  (Client)    │   :3020       │     (FastAPI)        │             │    (CLI)     │
└──────────────┘               └─────────────────────┘              └──────────────┘

왜 Docker가 아닌 네이티브 실행인가?

cursor agent CLI는 macOS ARM64 네이티브 바이너리와 Node.js 모듈로 구성되어 있습니다. Linux Docker 컨테이너에서는 실행할 수 없어 네이티브로 실행해야 합니다.

사전 요구사항

1. Cursor 설치: cursor.com에서 Cursor IDE 설치
2. cursor agent 인증:

   cursor agent login

3. Python 3.11+

설치

# 저장소 클론
git clone <repository-url>
cd cursor-agent-gateway

# 가상환경 생성 및 활성화
python -m venv venv
source venv/bin/activate

# 의존성 설치
pip install -r requirements.txt

실행 방법

방법 1: 직접 실행

source venv/bin/activate
python main.py

방법 2: launchd 서비스 (macOS, 권장)

자동 시작 및 재시작을 위한 macOS 서비스로 등록:

# 1. 로그 디렉토리 생성
mkdir -p logs

# 2. plist 파일 생성 (example 파일 복사 후 경로 수정)
cp com.cursor-agent-gateway.plist.example com.cursor-agent-gateway.plist

# 3. plist 파일 편집 - $PROJECT_PATH와 $HOME을 실제 경로로 변경
# 예: /Users/yourname/cursor-agent-gateway
vim com.cursor-agent-gateway.plist

# 4. 서비스 설치
cp com.cursor-agent-gateway.plist ~/Library/LaunchAgents/

# 5. 서비스 시작
launchctl load ~/Library/LaunchAgents/com.cursor-agent-gateway.plist

# 서비스 중지
launchctl unload ~/Library/LaunchAgents/com.cursor-agent-gateway.plist

# 로그 확인
tail -f logs/stdout.log
tail -f logs/stderr.log

API 엔드포인트

Health Check

curl http://localhost:3020/health

응답:

{
  "status": "healthy",
  "cursor_agent": "available",
  "timestamp": 1234567890.123
}

모델 목록

curl http://localhost:3020/v1/models

Chat Completions (Non-streaming)

curl -X POST http://localhost:3020/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonnet-4.5",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": false
  }'

Chat Completions (Streaming)

curl -X POST http://localhost:3020/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonnet-4.5",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'

지원 모델

모델 목록은 cursor agent CLI에서 동적으로 조회됩니다 (1시간 캐시).

curl http://localhost:3020/v1/models

현재 지원 모델 예시:

• auto - 자동 모델 선택
• sonnet-4.5, sonnet-4.5-thinking - Claude Sonnet 4.5
• opus-4.5, opus-4.5-thinking - Claude Opus 4.5
• gpt-5.2, gpt-5.1, gpt-5.1-codex-max - GPT 모델
• gemini-3-pro, gemini-3-flash - Gemini 모델
• grok, opus-4.1 등

OpenCode 연동

1. opencode.json 설정

~/.config/opencode/opencode.json에 provider 추가:

{
  "provider": {
    "cursor-agent": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Cursor Agent (Official CLI)",
      "options": {
        "baseURL": "http://localhost:3020/v1"
      },
      "models": {
        "sonnet-4.5": {
          "name": "Claude Sonnet 4.5 (Cursor)",
          "limit": { "context": 200000, "output": 64000 }
        },
        "opus-4.5": {
          "name": "Claude Opus 4.5 (Cursor)",
          "limit": { "context": 200000, "output": 64000 }
        },
        "gpt-5.2": {
          "name": "GPT 5.2 (Cursor)",
          "limit": { "context": 128000, "output": 16000 }
        }
      }
    }
  }
}

2. auth.json 설정

~/.local/share/opencode/auth.json에 추가 (API 키 불필요, 더미 값 사용):

{
  "cursor-agent": {
    "type": "api",
    "key": "cursor-agent-no-key-needed"
  }
}

3. 사용

# 모델 목록 확인
opencode models cursor-agent

# 실행
opencode -m cursor-agent/sonnet-4.5

프로젝트 구조

cursor-agent-gateway/
├── main.py                              # FastAPI 서버 (OpenAI 호환 API)
├── agent.py                             # cursor agent CLI 래퍼
├── config.py                            # 설정 (모델 목록, 포트 등)
├── converter.py                         # OpenAI ↔ Cursor 메시지 변환
├── requirements.txt                     # Python 의존성
├── com.cursor-agent-gateway.plist.example  # macOS launchd 설정 템플릿
└── logs/                                # 로그 디렉토리 (생성 필요)
    ├── stdout.log
    └── stderr.log

문제 해결

cursor agent 상태 확인

cursor agent status

"Logged in as ..." 메시지가 나와야 합니다.

재인증이 필요한 경우

cursor agent login

서비스 재시작

launchctl unload ~/Library/LaunchAgents/com.cursor-agent-gateway.plist
launchctl load ~/Library/LaunchAgents/com.cursor-agent-gateway.plist

포트 충돌

기본 포트 3020이 사용 중인 경우 config.py에서 변경:

PORT = 3021  # 원하는 포트로 변경

제한사항

• macOS 전용: cursor agent CLI가 macOS 네이티브 바이너리이므로 Linux/Windows에서는 사용 불가
• Cursor 구독 필요: Cursor Pro/Business 구독이 있어야 AI 모델 사용 가능
• 비공식 통합: Cursor의 공식 CLI를 사용하지만, 이 게이트웨이 자체는 비공식 프로젝트

라이선스

MIT License