Cursor Agent MCP Server

How to use

Interact with the Cursor Agent MCP server through an MCP client by selecting a registered tool and supplying the required arguments. You can use dedicated tools to perform precise tasks such as analyzing files, searching code, planning steps, editing patches, or simple chat prompts. Most tools share common options for how output is formatted and how prompts are echoed back to you, so you can tune verbosity and structure to your needs.

How to install

Prerequisites you need before starting the MCP server:

• Node.js 18+ (tested up to Node 22)
• A working cursor-agent CLI available in your PATH or at a known location

Additional configuration and notes

Configure how the server runs and how it interacts with the cursor-agent CLI through environment variables and command-line arguments. You can adjust the model used by the cursor-agent, set timeouts, and enable optional debugging prompts.

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

Troubleshooting

If you encounter common issues, check the following: the cursor-agent CLI is on PATH or its absolute path is configured; you provided a prompt when using print mode; and runtime timeouts or idle-kill settings aren’t cutting off a conversation prematurely. If the server output is empty, verify provider credentials and model name, and test the cursor-agent health directly.

Security and reliability notes

The MCP server starts child processes without a shell to prevent injection risks. Inputs are validated, and diagnostics can be enabled only when debugging is required. In normal operation, keep verbose diagnostics disabled to minimize noise and token usage.

Development and run commands

Start the server directly from its location once dependencies are installed.

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

Smoke test client to verify tools are accessible without an MCP host:

```bash
node ./cursor-agent-mcp/test_client.mjs "Hello from smoke test"
```

Run a raw tool to inspect behavior (no implicit print):

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

Tools available through the MCP server

The MCP server exposes a set of verb-centric tools that you can call via the MCP client. Each tool maps to a specific cursor-agent capability and accepts common options like output format and optional prompt echoing.

Example usage flows

- Analyze specific parts of your repository to identify architecture or module boundaries, then plan a task based on that analysis. - Run a focused code search across a subset of files and receive structured results in text, markdown, or JSON. - Edit a file by proposing a patch with a clear instruction and review the proposed changes before applying.

License

MIT (see package metadata for details).

cursor_agent_chat

Single-shot chat by passing the prompt as the final positional argument to the cursor-agent via the MCP server.

cursor_agent_edit_file

Prompt-based wrapper to edit a file or propose a patch, built from a structured instruction.

cursor_agent_analyze_files

Prompt-based analysis of repository scopes returning focused results and recommended paths to inspect.

cursor_agent_search_repo

Prompt-driven code search over the repository with optional include/exclude globs and formatted output.

cursor_agent_plan_task

Prompt-based planning tool that returns a numbered plan for a given goal.

cursor_agent_raw

Forwards raw argv to the CLI, with optional print behavior for fine-grained control.

cursor_agent_run

Legacy single-shot chat wrapper kept for compatibility.