@qmediat.io/cursor-mcp

MCP server for the Cursor CLI (cursor-agent): run Cursor's agent with any model id your plan offers — the Composer, Claude, GPT, Gemini and Grok families — through the Model Context Protocol.

Why this server?

• Any Cursor model — the model id is passed to cursor-agent --model as given; cursor_models lists what your CLI offers (Composer, Claude, GPT, Gemini, Grok families on your plan)
• 5 tools — agent execution, session continuation, model listing, session listing, health check
• Parallel execution — run multiple models simultaneously with built-in concurrency control (semaphore)
• Guarded execution — spawn without a shell, auto-approve only through the operator's environment (never a tool parameter), the client's cancellation and the timeout kill the child and its process group (SIGTERM, SIGKILL 5 s later; on Windows cursor-agent itself only)
• Minimal dependencies — only @modelcontextprotocol/sdk + zod
• Session management — resume conversations across calls

Quick Start

Prerequisites

1. Node.js >= 22.0.0 (developing it — npm run lint's Babel 8 — needs 22.18 or 24.11)
2. Cursor CLI installed and authenticated:

# Install the Cursor CLI (installs `agent`; `cursor-agent` stays as a legacy alias — the one this server resolves)
curl https://cursor.com/install -fsS | bash

# Authenticate (a Cursor account whose plan includes agent usage — see cursor.com/docs/models-and-pricing)
agent login

Requires Node.js 22 or newer.

Install

claude mcp add --scope user cursor-cli -- npx -y @qmediat.io/cursor-mcp

or by hand (below). npm install -g @qmediat.io/cursor-mcp installs the cursor-mcp command, which can replace the npx line in any config.

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 — an integer from 1 to 64; anything else is the default | | CURSOR_ALLOW_YOLO | No | false | true runs cursor_agent and cursor_reply with --force (auto-approve every tool call). Without it cursor-agent in headless mode only proposes file changes and applies none (Cursor's headless docs). DANGEROUS — only for trusted environments, best with CURSOR_SANDBOX=enabled | | CURSOR_SANDBOX | No | the CLI's default | enabled or disabled, passed as --sandbox <mode>: the sandbox confines what an auto-approved agent may run; any other value ends the server at startup | | CURSOR_KILL_GRACE_MS | No | 5000 | After SIGTERM (timeout or cancellation), a child still alive this long is sent SIGKILL — an integer of milliseconds from 1 to 2147483647 (what a timer can wait); anything else is the default |

Available Tools

| Tool | Description | Key Parameters | |------|-------------|----------------| | cursor_agent | Execute a prompt using Cursor's AI agent | prompt (≤ 100 000 chars), model, mode, workspace, timeout_seconds (10–3600, default 600) | | cursor_reply | Continue an existing agent session | prompt, session_id, model, timeout_seconds | | cursor_models | List the model ids the installed CLI offers | — | | cursor_sessions | List agent sessions (this server instance) | — | | cursor_health | Check installation, auth, and config | — |

Both agent tools run cursor-agent with --output-format stream-json: the answer, its session_id, request_id, the model cursor-agent reported, the duration, the number of tool calls and the files changed (write/edit targets, each once) come back as text and as structuredContent (outputSchema published). A client that sends a progress token on the request gets one notifications/progress per event (model, tool call, assistant message), so a ten-minute run never looks dead.

Models

model is passed to cursor-agent --model as given, so every id the installed CLI accepts works — the current list and prices are on cursor.com/docs/models-and-pricing, and cursor_models returns what your CLI reports (cursor-agent models). auto (the default) lets Cursor choose. This README names no ids on purpose: Cursor adds and retires models faster than this package releases, and a list here was what made 1.0.x reject every current model.

Modes

| Mode | Description | |------|-------------| | agent | Tools, terminal, search (default). In headless mode file changes are proposed in the answer, not applied, unless the operator set CURSOR_ALLOW_YOLO=true (--force) | | plan | Read-only planning — analyses and proposes a plan, makes no edits (in headless mode a clarifying question cannot be answered) | | 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=<a Composer id from cursor_models> → "Review this code"
Agent 2: cursor_agent with model=<a Claude id from cursor_models> → "Review this code"
Agent 3: cursor_agent with model=<a GPT id from cursor_models> → "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; the prompt follows a -- separator and the session id must be one word, so neither can read as a cursor-agent option (a prompt or session id of -f cannot turn into --force)
• No credentials stored — cursor-agent handles its own OAuth
• No HTTP requests — pure CLI wrapper, no network access beyond cursor-agent
• Process cleanup — the client's cancellation (the MCP request signal) and the timeout kill the child and the helpers in its process group (POSIX; on Windows there is no group and only cursor-agent itself is signalled): SIGTERM, then SIGKILL after CURSOR_KILL_GRACE_MS (5 s); the call and its concurrency slot are released only once the child itself has exited; the server's own shutdown ends every running group the same way, so no agent outlives it
• Auto-approve gated — --force requires explicit CURSOR_ALLOW_YOLO=true env var, never controllable by LLMs; without it the agent only proposes changes; CURSOR_SANDBOX=enabled confines an auto-approved agent; it applies to cursor_agent and cursor_reply alike
• Trusted workspace — every call runs cursor-agent --trust on the given workspace (the server's cwd by default), so the agent is not prompted about the directory: point workspace only at directories you intend it to operate in
• 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: auto (Cursor chooses)
/cursor-code --model <id> <task>                 # any id cursor_models lists

Run cursor_models to list the ids your CLI offers.

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". Works with any model id cursor_models lists (the Composer,
  Claude, GPT, Gemini and Grok families on your Cursor plan).
metadata:
  version: 1.1.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: `auto`, Cursor chooses)
- Everything else -> the task description

If user says a model name naturally (e.g. "use composer", "with gemini", "z grok"),
extract it and map to an id from cursor_models.

## 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 `auto`
- `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
npm run lint   # structure rules, repeated blocks, the baseline ratchet (docs/SYSTEMIC.md §1)
npm run format # Prettier (npm run lint checks it)
node dist/index.js

See CONTRIBUTING.md for guidelines; npm test builds and runs the smoke and argv tests.

Trademarks and affiliation

Cursor is a trademark of Anysphere. This is an independent, community-maintained integration published by Quantum Media Technologies sp. z o.o.; it is not affiliated with, sponsored by or endorsed by Anysphere. Use of the Cursor API or CLI through this server is subject to Anysphere's own terms and to your own API key or account.

License

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

Made by Quantum Media Technologies · more open source from qmediat