🖱️ Cursor Agent MCP

A fast, hardened Model Context Protocol server that lets any MCP host (Claude Code, Claude Desktop, and others) drive the Cursor Agent CLI.

Offload heavy, repo‑aware "thinking" — search, analysis, planning, edits — from your host model to cursor-agent, keeping the host's context small and your token bill low.

Why this exists

Large hosts like Claude Code burn tokens when they read big codebases directly. This server exposes a set of focused, verb-centric tools (chat, edit, analyze, search, plan, raw) that delegate the heavy lifting to the Cursor Agent CLI with tight scopes and concise outputs — so the host stays cheap and fast.

It also fixes a very real papercut: on Linux, cursor-agent -p can take 60–90 seconds just to start because it loads your desktop's MCP servers and syncs marketplace plugins before answering. This server ships a bare_config mode that runs the CLI against an isolated config directory, cutting cold starts to ~15 seconds — without touching your real ~/.cursor setup.

flowchart LR
    A[Claude / MCP host] -- stdio --> B[Cursor Agent MCP]
    B -- spawn --> C[cursor-agent CLI]
    C -- isolated CURSOR_CONFIG_DIR --> D[(no user MCPs/plugins<br/>fast startup)]
    C --> E[Model: auto / gpt-5 / composer-2]

Related MCP server: cursor-mcp-server

Highlights

• ⚡ bare_config fast mode — isolated CURSOR_CONFIG_DIR skips user MCPs/plugins (~90s → ~15s on Linux).

• 🧰 10 tools — chat, edit, analyze, search, plan, raw, legacy run, plus async start/check/cancel for long jobs.

• 🔑 First-class auth & model — pass api_key and model per call or via env; API keys are redacted in debug logs.

• 🧵 Async jobs — fire long tasks in the background and poll them without hitting tool-call timeouts.

• 🛡️ Hardened spawning — shell: false (no injection), Zod-validated inputs, robust timeouts and optional idle-kill.

• 🔌 Host-agnostic — works with Claude Code, Claude Desktop, or any stdio MCP client.

Requirements

• Node.js 18+ (tested through Node 22)

• Cursor Agent CLI on your PATH as agent or cursor-agent (or point to it with CURSOR_AGENT_PATH)

• A Cursor API key (crsr_…) if you use bare_config (an isolated config can't reuse the desktop login)

# verify the CLI is available
agent --version

Install the CLI from the Cursor CLI docs if it's missing.

Installation

git clone https://github.com/lipey1/cursor-agent-mcp.git
cd cursor-agent-mcp
npm install        # or: npm ci

Run it directly (stdio):

node ./server.js

Most of the time you won't run it by hand — your MCP host launches it for you (see below).

Configure your MCP host

Add an entry pointing at server.js. Recommended fast defaults:

{
  "mcpServers": {
    "cursor-agent": {
      "command": "node",
      "args": ["/absolute/path/to/cursor-agent-mcp/server.js"],
      "env": {
        "CURSOR_AGENT_PATH": "/home/you/.local/bin/agent",
        "CURSOR_API_KEY": "crsr_your_key_here",
        "CURSOR_AGENT_MODEL": "auto",
        "CURSOR_AGENT_FORCE": "1",
        "CURSOR_AGENT_TRUST": "1",
        "CURSOR_AGENT_BARE_CONFIG": "1",
        "CURSOR_AGENT_TIMEOUT_MS": "0",
        "CURSOR_AGENT_ASYNC_MAX_MS": "0"
      }
    }
  }
}

Never commit your real key. Put it in the host's MCP env (or your shell environment), not in a tracked file.

• Claude Code: add the block to your project's .mcp.json.

• Claude Desktop: add it under mcpServers in claude_desktop_config.json.

The bare_config fast path

On Linux, the Cursor Agent CLI loads ~/.cursor/mcp.json and syncs marketplace plugins (Prisma, Figma, Notion, …) before it answers — often 60–90 seconds of pure startup, even for a one-line question.

Setting CURSOR_AGENT_BARE_CONFIG=1 (or bare_config: true per call) points the CLI at an isolated CURSOR_CONFIG_DIR (~/.cursor-agent-mcp by default). It skips your desktop MCPs and plugins entirely.

OpenTelemetry fan-out alone can add ~15–50s per call (CDN contacts on every spawn). This server disables it in the child process by default.

Because the isolated config has no saved login, provide an API key when using this mode.

Tools

All tools share a COMMON set of arguments:

Examples

Chat (fast mode, explicit model):

{
  "name": "cursor_agent_chat",
  "arguments": {
    "prompt": "Who created React?",
    "model": "auto",
    "bare_config": true
  }
}

Scoped code search:

{
  "name": "cursor_agent_search_repo",
  "arguments": {
    "query": "fetch(",
    "include": ["src/**/*.ts", "app/**/*.tsx"],
    "exclude": ["node_modules/**", "dist/**"],
    "output_format": "markdown"
  }
}

Long task without timeouts:

// 1) start
{ "name": "cursor_agent_start", "arguments": { "prompt": "Refactor the auth module and add tests", "label": "auth-refactor" } }
// → returns { "job_id": "job_1_..." }

// 2) poll until status is completed/failed
{ "name": "cursor_agent_check", "arguments": { "job_id": "job_1_...", "full": true } }

Environment variables

Quick smoke test

A tiny stdio client is included:

# list tools and call chat
node ./test_client.mjs "Hello from smoke test"

# fast mode + explicit key
CURSOR_AGENT_BARE_CONFIG=1 \
CURSOR_API_KEY="crsr_your_key" \
node ./test_client.mjs "Say only OK"

# call the raw tool with --help (no implicit --print)
TEST_TOOL=cursor_agent_raw TEST_ARGV='["--help"]' node ./test_client.mjs

Troubleshooting

Security notes

• Child processes are spawned with shell: false — no shell injection or quoting pitfalls.

• All tool inputs are validated with Zod.

• API keys passed via argv are redacted in debug logs; prefer env over per-call api_key.

• bare_config isolates only the CLI's config directory — it never modifies your real ~/.cursor.

• .gitignore excludes .env, keys, and the bare config dir so secrets don't get committed.

Project layout

cursor-agent-mcp/
├── server.js          # MCP server: tools, spawning, async jobs
├── test_client.mjs    # stdio smoke-test client
├── package.json
├── misc/              # Host/agent instruction docs (cost-aware usage)
├── LICENSE
└── README.md

Credits

This project builds on the original sailay1996/cursor-agent-mcp. Enhancements in this fork — model/API-key options, bare_config fast startup, --trust handling, async job hardening, and this documentation — by Felipe Estrela.

License

MIT — see the license file for details.