Cursor Agent MCP

🚀 Cursor Agent MCP Server

A minimal, hardened Model Context Protocol (MCP) server that wraps the cursor-agent CLI. It offers 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

🚀 Quick Start

Installation

1. Clone or download this repository.
2. Install dependencies for the MCP server:

cd ./cursor-agent-mcp
npm ci        # or: npm install

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

cursor-agent --version

4. Run the MCP server:

# from the server directory
node ./server.js

# or from the repo root using the provided script
npm --prefix ./cursor-agent-mcp run start

Quick smoke test (without an MCP host)

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

# list tools and call chat with a prompt
node ./cursor-agent-mcp/test_client.mjs "Hello from smoke test"

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

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

✨ 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

📦 Installation

The installation steps are described in the "Quick Start" section above.

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.

💻 Usage Examples

Usage inside Claude

• Call any of the tools described below; arguments map 1:1 to the JSON fields in the “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.

Tool Examples

1) cursor_agent_chat

{
  "name": "cursor_agent_chat",
  "arguments": { "prompt": "Explain SIMD in one paragraph", "output_format": "markdown" }
}

2) cursor_agent_edit_file

{
  "name": "cursor_agent_edit_file",
  "arguments": {
    "file": "src/app.ts",
    "instruction": "Extract the HTTP client into a separate module and add retries",
    "dry_run": true,
    "output_format": "markdown"
  }
}

3) cursor_agent_analyze_files

{
  "name": "cursor_agent_analyze_files",
  "arguments": {
    "paths": ["src", "scripts"],
    "prompt": "Give me a concise architecture overview with module boundaries"
  }
}

4) cursor_agent_search_repo

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

5) cursor_agent_plan_task

{
  "name": "cursor_agent_plan_task",
  "arguments": {
    "goal": "Set up CI to lint and test this repo",
    "constraints": ["GitHub Actions", "Node 18"]
  }
}

6) cursor_agent_raw

{ "name": "cursor_agent_raw", "arguments": { "argv": ["--help"], "print": false } }

{ "name": "cursor_agent_raw", "arguments": { "argv": ["-m","gpt-5","What is SIMD?"], "print": true } }

7) cursor_agent_run (legacy)

{
  "name": "cursor_agent_run",
  "arguments": { "prompt": "Your prompt here", "output_format": "text" }
}

📚 Documentation

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.

Configuration for MCP hosts

Example Claude Code/Claude Desktop entry:

{
  "mcpServers": {
    "cursor-agent": {
      "command": "node",
      "args": ["/abs/path/to/cursor-agent-mcp/server.js"],
      "env": {
        "CURSOR_AGENT_ECHO_PROMPT": "1",
        "CURSOR_AGENT_FORCE": "true",
        "CURSOR_AGENT_PATH": "/home/you/.local/bin/cursor-agent",
        "CURSOR_AGENT_MODEL": "gpt-5",
        "CURSOR_AGENT_IDLE_EXIT_MS": "0",
        "CURSOR_AGENT_TIMEOUT_MS": "60000"
      }
    }
  }
}

Optional: enable debug logs

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

{
  "mcpServers": {
    "cursor-agent": {
      "command": "node",
      "args": ["/abs/path/to/cursor-agent-mcp/server.js"],
      "env": {
        "CURSOR_AGENT_ECHO_PROMPT": "1",
        "CURSOR_AGENT_FORCE": "true",
        "CURSOR_AGENT_PATH": "/home/you/.local/bin/cursor-agent",
        "CURSOR_AGENT_MODEL": "gpt-5",
        "CURSOR_AGENT_IDLE_EXIT_MS": "0",
        "CURSOR_AGENT_TIMEOUT_MS": "60000",
        "DEBUG_CURSOR_MCP": "1"
      }
    }
  }
}

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

🔧 Technical Details

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.

📄 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

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)