<div align="center">

🖱️ 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.

</div>

---

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]

---

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.

Configuration	Cold start	Notes
Default (loads ~/.cursor)	~60–90s	Your real desktop MCPs + marketplace plugins
bare_config: true	~15–20s	Isolated config; your ~/.cursor is untouched
+ telemetry disabled (default)	~15–20s	Child gets OTEL_SDK_DISABLED=true (set CURSOR_AGENT_KEEP_TELEMETRY=1 to opt back in)

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:

Arg	Type	Description
output_format	"text" | "json" | "markdown"	Response format (default text)
model	string	CLI model id (auto, gpt-5, composer-2, …); overrides CURSOR_AGENT_MODEL
api_key	string	Cursor API key; prefer setting it via env
force	boolean	Pass --force (run shell without prompts)
trust	boolean	Pass --trust (default true)
bare_config	boolean	Use the isolated fast config
config_dir	string	Explicit CURSOR_CONFIG_DIR override
cwd	string	Working directory for the CLI
executable	string	Explicit path to the CLI binary
extra_args	string[]	Extra argv passed through
echo_prompt	boolean	Prepend the effective prompt to the result

Tool	Purpose
cursor_agent_chat	One-shot chat with a prompt
cursor_agent_edit_file	Prompt-based file edit (diff or apply)
cursor_agent_analyze_files	Analyze one or more paths
cursor_agent_search_repo	Code search with include/exclude globs
cursor_agent_plan_task	Produce a numbered plan for a goal
cursor_agent_raw	Escape hatch: pass raw argv to the CLI
cursor_agent_run	Legacy single-shot chat (kept for compatibility)
cursor_agent_start	Start a long task in the background → job_id
cursor_agent_check	Poll a background job_id
cursor_agent_cancel	Kill a background job

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

Variable	Meaning
CURSOR_AGENT_PATH	Absolute path to agent / cursor-agent (default: agent on PATH)
CURSOR_API_KEY / CURSOR_AGENT_API_KEY	API key passed as --api-key and into the child env
CURSOR_AGENT_MODEL	Default model (--model)
CURSOR_AGENT_FORCE	"1"/"true" → inject --force
CURSOR_AGENT_TRUST	"1"/"true" → inject --trust (default true)
CURSOR_AGENT_BARE_CONFIG / CURSOR_AGENT_FAST	"1" → isolated CURSOR_CONFIG_DIR
CURSOR_AGENT_BARE_CONFIG_DIR	Where the bare config lives (default ~/.cursor-agent-mcp)
CURSOR_AGENT_CONFIG_DIR	Always use this CURSOR_CONFIG_DIR (even without the bare flag)
CURSOR_AGENT_TIMEOUT_MS	Hard runtime ceiling per call (default 30000); "0" disables
CURSOR_AGENT_ASYNC_MAX_MS	Max lifetime for async jobs (default 1800000); "0" disables
CURSOR_AGENT_IDLE_EXIT_MS	Idle-kill threshold; "0" disables (recommended)
CURSOR_AGENT_KEEP_TELEMETRY	"1" → keep CLI OpenTelemetry on; default is off (OTEL_SDK_DISABLED=true in the child)
CURSOR_AGENT_ECHO_PROMPT	"1" → prepend the prompt to the result
DEBUG_CURSOR_MCP	"1" → stderr diagnostics (API keys redacted)

---

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

Symptom	Fix
agent not found	Set CURSOR_AGENT_PATH or add the CLI to PATH
~60–90s before the first token	Enable CURSOR_AGENT_BARE_CONFIG=1 or bare_config: true
Auth error / 401	Set CURSOR_API_KEY (or CURSOR_AGENT_API_KEY), or pass api_key per call
Cut off mid-answer	Raise CURSOR_AGENT_TIMEOUT_MS or set it to "0" to disable; keep CURSOR_AGENT_IDLE_EXIT_MS=0
Empty output	Verify the model id and credentials; try cursor_agent_raw with argv: ["--version"]

---

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.