Cursor Agent MCP Server

Minimal, hardened Model Context Protocol (MCP) server that wraps the cursor-agent CLI and exposes multiple, Claude‑friendly tools for chat, repository analysis, code search, planning, and more.

Core implementation: cursor-agent-mcp/server.js Test harness: cursor-agent-mcp/test_client.mjs Package manifest: cursor-agent-mcp/package.json

Purpose: reduce token usage and cost in Claude Code

This MCP exists to offload heavy “thinking” and repo‑aware tasks from the host (e.g., Claude Code) to the cursor-agent CLI. By letting the CLI handle analysis/planning/search with focused, prompt‑based instructions, you can:

• Scope work to only the needed files/paths instead of streaming the entire workspace.

• Choose a cost‑effective model via environment (or per call) and keep the host’s context small.

• Control response verbosity through output_format ("text" | "markdown" | "json") and tailored prompts.

• Use specialized tools (analyze, search, plan, edit) that produce targeted outputs rather than general chat.

Cost‑control tips

• Prefer precise scopes:

  • Use include/exclude globs with cursor_agent_search_repo and curated paths for cursor_agent_analyze_files.

• Pick output formats intentionally:

  • Use "text" or "markdown" for concise answers. Reserve "json" only when you truly need structured output (it’s usually larger).

• Select a model that matches the task:

  • Set CURSOR_AGENT_MODEL to a cost‑effective default; override per tool call only when necessary.

• Avoid unnecessary echo/debug:

  • CURSOR_AGENT_ECHO_PROMPT=1 is helpful during setup, but disables it later to save tokens in host logs.

  • Keep DEBUG_CURSOR_MCP off in normal use; it writes diagnostics to stderr (not counted in host tokens, but noisy).

• Control runtime instead of idle‑kill:

  • Keep CURSOR_AGENT_IDLE_EXIT_MS="0" so valid runs aren’t cut mid‑generation. Bound cost/time with CURSOR_AGENT_TIMEOUT_MS and focused prompts.

• Use cursor_agent_raw thoughtfully:

  • It’s powerful and can stream detailed sessions; for cheapest usage, prefer the focused tools with concise prompts and "text" output.

Related MCP server: Cursor MCP Server

Features

• Multi‑tool surface modeled after “verb-centric” CLIs

• Works well in Claude Code and other MCP hosts

• Safe process spawn (no shell), robust timeout handling

• Optional prompt echoing for easy debugging inside hosts

• Configurable defaults via environment variables (model, force, timeouts, executable path)

• Backward‑compatible legacy tool for single‑shot chat

Requirements

• Node.js 18+ (tested up to Node 22)

• A working cursor-agent CLI in your PATH or at an explicit location

• Provider credentials configured for your chosen model (e.g., via the CLI’s own mechanism)

Installation

1. Clone or download this repository.

2. Install dependencies for the MCP server:

3. Ensure the cursor-agent CLI is installed and on PATH (or set CURSOR_AGENT_PATH):

4. Run the MCP server:

Do I need npx?

No. This server runs directly from the repository and is not published to npm (package.json sets "private": true). Use Node to execute server.js after installing dependencies as shown above.

If you later publish this as an npm package and add a bin entry in package.json, you could run it with npx and point your MCP host to that executable instead. Until then, prefer the Node-based command shown here.

Quick smoke test (without an MCP host)

A tiny client is provided to list tools and call one of them over stdio:

The client uses the same stdio transport a host would use. See JavaScript.main().

How it works

All tool calls ultimately invoke the same executor JavaScript.invokeCursorAgent(), which:

• Resolves the cursor-agent executable (explicit path or PATH)

• Injects --print and --output-format <fmt> by default

• Optionally adds -m <model> and -f based on env/args

• Streams stdout/stderr and enforces a total timeout

• Optionally kills long‑idle processes (disabled by default)

The legacy wrapper JavaScript.runCursorAgent() accepts a prompt and optional flags, composing the argv and delegating to the executor.

Tools

These tools are registered in JavaScript.server.tool() and below. All tools share the “COMMON” arguments:

• output_format: "text" | "json" | "markdown" (default "text")

• extra_args?: string[]

• cwd?: string

• executable?: string

• model?: string

• force?: boolean

• echo_prompt?: boolean → prepend “Prompt used: …” to the result

1) cursor_agent_chat

• Args: { prompt: string, ...COMMON }

• Behavior: Single‑shot chat by passing the prompt as the final positional argument.

• Code path: JavaScript.server.tool() → JavaScript.runCursorAgent()

Example:

2) cursor_agent_edit_file

• Args: { file: string, instruction: string, apply?: boolean, dry_run?: boolean, prompt?: string, ...COMMON }

• Behavior: Prompt‑based wrapper. Builds a structured instruction that asks the agent to edit or propose a patch for the file.

• Code path: JavaScript.server.tool()

Example:

3) cursor_agent_analyze_files

• Args: { paths: string | string[], prompt?: string, ...COMMON }

• Behavior: Prompt‑based repository/file analysis listing the paths to focus on.

• Code path: JavaScript.server.tool()

Example:

4) cursor_agent_search_repo

• Args: { query: string, include?: string | string[], exclude?: string | string[], ...COMMON }

• Behavior: Prompt‑based code search over the repo, with optional include/exclude globs.

• Code path: JavaScript.server.tool()

Example:

5) cursor_agent_plan_task

• Args: { goal: string, constraints?: string[], ...COMMON }

• Behavior: Prompt‑based planning tool that returns a numbered plan for your goal.

• Code path: JavaScript.server.tool()

Example:

6) cursor_agent_raw

• Args: { argv: string[], print?: boolean, ...COMMON }

• Behavior: Forwards raw argv to the CLI. Defaults to print=false to avoid adding --print; set print=true to inject it.

• Code path: JavaScript.server.tool()

Examples:

7) cursor_agent_run (legacy)

• Args: { prompt: string, ...COMMON }

• Behavior: Original single‑shot chat wrapper; maintained for compatibility.

• Code path: JavaScript.server.tool()

Configuration for MCP hosts

Example Claude Code/Claude Desktop entry:

Optional: enable debug logs

Add DEBUG_CURSOR_MCP=1 to print diagnostics to stderr (spawn argv, prompt preview, exit). Useful while integrating or troubleshooting.

Note: many hosts don’t display server stderr logs. To see the effective prompt in the UI, use CURSOR_AGENT_ECHO_PROMPT=1 or pass "echo_prompt": true in tool arguments. Implementation points:

• debug spawn/exit logs: JavaScript.invokeCursorAgent()

• prompt preview: JavaScript.runCursorAgent()

Environment variables understood by the server:

• CURSOR_AGENT_PATH: absolute path to the cursor-agent binary; falls back to PATH

• CURSOR_AGENT_MODEL: default model (appended as -m <model> unless you already provided one)

• CURSOR_AGENT_FORCE: "true"/"1" to inject -f unless already present

• CURSOR_AGENT_TIMEOUT_MS: hard runtime ceiling (default 30000)

• CURSOR_AGENT_IDLE_EXIT_MS: idle‑kill threshold in ms; "0" disables idle kill (recommended)

• CURSOR_AGENT_ECHO_PROMPT: "1" to prepend the effective prompt to the tool’s result

• DEBUG_CURSOR_MCP: "1" to log spawn/exit diagnostics to stderr

Usage inside Claude

• Call any of the tools described above; arguments map 1:1 to the JSON fields in “Tools” section.

• To see the exact prompt, either set CURSOR_AGENT_ECHO_PROMPT=1 globally or pass "echo_prompt": true in the tool call.

• For advanced use, prefer cursor_agent_raw for precise control of argv and print behavior.

Troubleshooting

• “cursor-agent not found”

  • Set CURSOR_AGENT_PATH to the absolute path of the CLI or ensure it’s on PATH.

• “No prompt provided for print mode”

  • You called RAW with print=true but without a prompt. Either provide a prompt in argv or set print=false.

• Premature termination mid‑generation

  • Increase CURSOR_AGENT_TIMEOUT_MS, and keep CURSOR_AGENT_IDLE_EXIT_MS at "0".

• Empty tool output

  • Verify provider credentials and model name. Try cursor_agent_raw with argv: ["--version"] to confirm CLI health.

Development

• Start the server directly:

  • node ./cursor-agent-mcp/server.js

• Smoke client:

  • node ./cursor-agent-mcp/test_client.mjs "hello"

  • TEST_TOOL=cursor_agent_raw TEST_ARGV='["--help"]' node ./cursor-agent-mcp/test_client.mjs

• Useful env while developing:

  • DEBUG_CURSOR_MCP=1 CURSOR_AGENT_ECHO_PROMPT=1

Key entry points:

• Executor: JavaScript.invokeCursorAgent()

• Legacy runner: JavaScript.runCursorAgent()

• Tool registrations start at: JavaScript.server.tool()

Security notes

• Child processes are spawned with shell: false to avoid shell injection and quoting issues.

• Inputs are validated with Zod; unknown types are rejected.

• Avoid logging secrets; DEBUG only prints argv and minimal env context.

Versioning

Current server version: 1.1.0 (see cursor-agent-mcp/package.json)

License

MIT (see cursor-agent-mcp/package.json)

Acknowledgements

• MCP protocol and SDK by the Model Context Protocol team

• Inspiration: multi‑verb MCP servers such as gemini‑mcp‑tool