@qmediat.io/cursor-mcp

MCP server for Cursor CLI — access Composer 2, Claude, GPT, Gemini, and Grok models through the Model Context Protocol.

Why this server?

• Multi-model access — Composer 2, Claude 4.6 Opus, GPT-5.4, Gemini 3 Pro, Grok, Kimi K2.5 through a single interface
• 5 tools — agent execution, session continuation, model listing, session listing, health check
• Parallel execution — run multiple models simultaneously with built-in concurrency control (semaphore)
• Security-first — spawn (no shell), auto-approve gated by env var (never LLM-controllable), AbortSignal cancellation
• Minimal dependencies — only @modelcontextprotocol/sdk + zod
• Session management — resume conversations across calls

Quick Start

Prerequisites

1. Node.js >= 22.0.0
2. Cursor CLI installed and authenticated:

# Install cursor-agent
curl https://cursor.com/install -fsS | bash

# Authenticate (requires Cursor Pro/Business subscription)
cursor-agent login

Install

npm install -g @qmediat.io/cursor-mcp

Or run directly with npx:

npx @qmediat.io/cursor-mcp

Configuration

Claude Code (~/.claude.json)

{
  "mcpServers": {
    "cursor-cli": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@qmediat.io/cursor-mcp"]
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "cursor-cli": {
      "command": "npx",
      "args": ["-y", "@qmediat.io/cursor-mcp"]
    }
  }
}

Local development

{
  "mcpServers": {
    "cursor-cli": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/cursor-mcp/dist/index.js"]
    }
  }
}

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | CURSOR_MAX_CONCURRENCY | No | 3 | Maximum concurrent cursor-agent processes | | CURSOR_ALLOW_YOLO | No | false | Enable --force mode (auto-approve all tool calls). DANGEROUS — only for trusted environments |

Available Tools

| Tool | Description | Key Parameters | |------|-------------|----------------| | cursor_agent | Execute a prompt using Cursor's AI agent | prompt, model, mode, workspace, cloud, timeout_seconds | | cursor_reply | Continue an existing agent session | prompt, session_id, model, timeout_seconds | | cursor_models | List all available AI models | — | | cursor_sessions | List agent sessions (this server instance) | — | | cursor_health | Check installation, auth, and config | — |

Models

| Model | Description | Pricing (input/output per 1M tokens) | |-------|-------------|---------------------------------------| | auto | Cursor auto-selects (default) | varies | | composer-2 | Cursor Composer 2 — 200K context | $0.50 / $2.50 | | composer-2-fast | Composer 2 fast variant | $1.50 / $7.50 | | cursor/claude-4-sonnet | Claude 4 Sonnet via Cursor | varies | | cursor/claude-4.5-sonnet | Claude 4.5 Sonnet via Cursor | varies | | cursor/claude-4.6-opus-high | Claude 4.6 Opus via Cursor | varies | | cursor/gpt-5.1 | GPT-5.1 via Cursor | varies | | gpt-5.4 | GPT-5.4 | varies | | cursor/gemini-3-flash | Gemini 3 Flash via Cursor | varies | | gemini-3-pro | Gemini 3 Pro | varies | | cursor/grok | Grok via Cursor | varies | | kimi-k2.5 | Moonshot Kimi K2.5 | varies |

Modes

| Mode | Description | |------|-------------| | agent | Full capabilities — file edit, terminal, search (default) | | plan | Design-focused — asks clarifying questions before acting | | ask | Read-only exploration — no file modifications |

Parallel Execution

Run multiple models simultaneously by making parallel tool calls:

# In Claude Code, spawn 3 Agent subprocesses:
Agent 1: cursor_agent with model=composer-2 → "Review this code"
Agent 2: cursor_agent with model=cursor/claude-4-sonnet → "Review this code"
Agent 3: cursor_agent with model=gpt-5.4 → "Review this code"

The built-in semaphore (default: 3) queues excess requests to prevent rate limit errors.

Security

• No shell execution — child_process.spawn with argument arrays, preventing injection
• No credentials stored — cursor-agent handles its own OAuth
• No HTTP requests — pure CLI wrapper, no network access beyond cursor-agent
• Process cleanup — AbortSignal kills child processes on client disconnect or timeout
• Auto-approve gated — --force requires explicit CURSOR_ALLOW_YOLO=true env var, never controllable by LLMs
• Concurrency limited — semaphore prevents resource exhaustion

See SECURITY.md for full details.

Supervised Coding Skill

Optional Claude Code skill that lets Claude Code act as a supervisor while any Cursor model does the coding.

How it works: Claude Code analyzes the task, sends precise instructions to Cursor via cursor_agent, reviews the output by reading actual files from disk, and iterates with cursor_reply until satisfied (max 3 rounds).

Prerequisite: The cursor-cli MCP server (this package) must be installed and configured in Claude Code first.

Usage

/cursor-code <task>                          # default: composer-2
/cursor-code --model gpt-5.4 <task>          # explicit model
/cursor-code --model cursor/grok <task>      # any model from cursor_models

Run cursor_models to list all available model IDs.

Install the skill

mkdir -p ~/.claude/skills/cursor-code

Create ~/.claude/skills/cursor-code/SKILL.md with the following content:

---
name: cursor-code
description: Delegate coding to any Cursor model while Claude Code supervises.
  Use when user says "cursor-code", "delegate to cursor", "cursor code this",
  or "/cursor-code". Supports all models from cursor_models (Composer 2, GPT 5.4,
  Gemini 3.1 Pro, Grok 4.20, Claude 4.6 Sonnet, Kimi K2.5, etc.).
metadata:
  version: 1.0.0
---

# Supervised Coding: Claude Code (Supervisor) -> Cursor (Coder)

You are the **supervisor** (Claude Code). A Cursor model is the **coder**.
You give precise instructions, the coder writes code, you review and iterate.

## Parsing

Extract from user input:
- `--model <id>` -> model to use (default: `composer-2`)
- Everything else -> the task description

If user says a model name naturally (e.g. "use gpt-5.4", "with gemini", "z grok"),
extract it and map to the cursor_models ID.

## Workflow

### Step 1: Analyze
- Read the relevant files to understand current state
- Break the user's task into a single, focused coding instruction
- Identify: target files, constraints, acceptance criteria

### Step 2: Instruct
Call `cursor_agent` with:
- `model`: extracted model or `composer-2`
- `workspace`: current working directory
- `prompt`: precise instruction with file paths, function names, constraints
- Keep prompt focused -- one task per call, not an entire feature
- Extract and store the `session_id` from the response for use in Step 4

Output before calling: `[cursor-cli -> <model>]`

### Step 3: Verify
After the coder returns:
- Run `git diff --name-only` to discover ALL files the coder modified
- Read EVERY modified file from disk (use Read tool) -- not just the ones from your prompt
- Diff against expectations
- Check: correctness, edge cases, security, type safety

### Step 4: Iterate (max 3 rounds)
If issues found:
- Call `cursor_reply` with the same session_id
- Give specific fix instructions (file:line, what's wrong, what to do)
- Re-verify after each round
- If the coder is fundamentally off-track (wrong approach, not just small bugs),
  abandon the session early and start fresh with a more explicit prompt

### Step 5: Report
Summarize to the user:
- Model used (confirm from response, not just request)
- What was done
- Files changed
- Rounds needed (1 = clean, 2-3 = corrections applied)
- Any manual fixes Claude Code applied directly

## Rules
- ONE task per cursor_agent call -- don't batch entire features
- ALWAYS read files from disk after coder finishes
- NEVER trust cached file contents -- Cursor writes directly to disk
- Set timeout_seconds appropriately (30-120s for typical tasks)
- If the task is trivial (< 5 lines) -- just do it yourself, don't delegate
- Follow model transparency rules -- always state [cursor-cli -> model] before call
- If cursor_agent/cursor_reply fails (timeout, auth, CLI not found) -- report the error to the user and run cursor_health to diagnose. Do not retry silently
- If unsure about valid model IDs -- call cursor_models first

Restart Claude Code after creating the skill file.

Development

git clone https://github.com/qmediat/cursor-mcp.git
cd cursor-mcp
npm install
npm run build
node dist/index.js

See CONTRIBUTING.md for guidelines.

License

MIT - Quantum Media Technologies sp. z o.o.