Skip to main content
Glama
Cursor Agent MCP Server

Cursor Agent MCP Server

by Darkstar326

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.

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:

cd ./cursor-agent-mcp
npm ci        # or: npm install
  1. Ensure the cursor-agent CLI is installed and on PATH (or set CURSOR_AGENT_PATH):

cursor-agent --version
  1. 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

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:

# 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().

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

Example:

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

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:

{
  "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

  • 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:

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

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:

{
  "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

  • 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:

{
  "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

  • 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:

{ "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)

  • 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:

{
  "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:

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:

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

Available Tools

7 tools
cursor_agent_analyze_filesC

Analyze one or more paths; optional prompt. Prompt-based wrapper.

Inputs: paths (required), prompt, output_format, extra_args, +5 more.

cursor_agent_chatC

Chat with cursor-agent using a prompt and optional model/force/output_format.

Inputs: prompt (required), output_format, extra_args, cwd, +4 more.

cursor_agent_edit_fileC

Edit a file with an instruction. Prompt-based wrapper; no CLI subcommand required.

Inputs: file (required), instruction (required), apply, dry_run, +8 more.

cursor_agent_plan_taskC

Generate a plan for a goal with optional constraints. Prompt-based wrapper.

Inputs: goal (required), constraints, output_format, extra_args, +5 more.

cursor_agent_rawC

Advanced: provide raw argv array to pass after common flags (e.g., ["search","--query","foo"]).

Inputs: argv (required), print, output_format, extra_args, +5 more.

cursor_agent_runC

Run cursor-agent with a prompt and desired output format (legacy single-shot).

Inputs: prompt (required), output_format, extra_args, cwd, +3 more.

cursor_agent_search_repoC

Search repository code with include/exclude patterns. Prompt-based wrapper.

Inputs: query (required), include, exclude, output_format, +6 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 7 tools

    Disambiguation3/5

    The tools have overlapping purposes that could cause confusion, particularly between cursor_agent_chat and cursor_agent_run which both involve prompt-based interaction with cursor-agent. Additionally, cursor_agent_raw is described as 'advanced' but its functionality might overlap with other tools, creating ambiguity in tool selection for specific tasks.

    Naming Consistency5/5

    All tool names follow a consistent snake_case pattern with the prefix 'cursor_agent_' followed by a verb_noun combination (e.g., analyze_files, chat, edit_file). This uniformity makes the tool set predictable and easy to parse, with no deviations in naming conventions.

    Tool Count4/5

    With 7 tools, the count is reasonable for a server focused on cursor-agent interactions, covering analysis, chat, editing, planning, raw commands, running, and searching. It is slightly on the lower side but still well-scoped for its purpose, with each tool appearing to serve a distinct role in the workflow.

    Completeness4/5

    The tool set covers key operations for interacting with cursor-agent, including analysis, chat, file editing, task planning, raw command execution, running prompts, and repository search. Minor gaps might exist, such as lack of tools for managing agent settings or handling multi-step workflows, but core functionalities are adequately represented for the domain.

    Related MCP Connectors