# cursor-mcp [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/qmediat/cursor-mcp  
**GitHub Stars:** 1  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/cursor-mcp

## Description
Cursor's agent (cursor-agent CLI) through MCP: any model your plan offers, resumable sessions.

## Tools
Capabilities this server exposes over MCP:

- **cursor_agent** — Execute a prompt using Cursor's AI agent
- **cursor_reply** — Continue an existing agent session
- **cursor_models** — List the model ids the installed CLI offers
- **cursor_sessions** — List agent sessions (this server instance)
- **cursor_health** — Check installation, auth, and config

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "cursor-mcp": {
    "command": "npx",
    "args": ["-y","@qmediat.io/cursor-mcp"],
    "env": {
      "CURSOR_MAX_CONCURRENCY": "",
      "CURSOR_ALLOW_YOLO": "",
      "CURSOR_SANDBOX": "",
      "CURSOR_KILL_GRACE_MS": ""
    }
  }
}
```

**Requires environment variables:** `CURSOR_MAX_CONCURRENCY`, `CURSOR_ALLOW_YOLO`, `CURSOR_SANDBOX`, `CURSOR_KILL_GRACE_MS` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What cursor-mcp MCP server does

The cursor-mcp MCP server wraps Cursor’s `cursor-agent` command-line interface and exposes it through the Model Context Protocol. An MCP client can send a prompt to Cursor, select a model accepted by the local CLI, choose an operating mode, and specify a workspace and timeout. The server returns the agent response together with session and request identifiers, the reported model, duration, tool-call count, and files changed.

Five tools are available:

- `cursor_agent` starts an agent request.
- `cursor_reply` continues an existing session by its session ID.
- `cursor_models` reports model IDs offered by the installed CLI.
- `cursor_sessions` lists sessions known to this server instance.
- `cursor_health` checks Cursor CLI installation, authentication, and configuration.

Supported model IDs are not hard-coded. The selected value is passed to Cursor, while `auto` allows Cursor to choose. The README identifies Composer, Claude, GPT, Gemini, and Grok model families as examples available on applicable plans.

## How it works

The package communicates over MCP using standard input and output. Each agent call starts `cursor-agent` with argument arrays rather than a shell, and the prompt is separated from command-line options. Agent output is consumed in stream-JSON format. Clients that provide a progress token receive progress events for model activity, tool calls, and assistant messages.

Calls can run concurrently, with a semaphore limiting active Cursor processes. The default limit is three and can be changed through configuration. Timeouts and request cancellation terminate the child process; the server first sends SIGTERM and later sends SIGKILL if needed. Server shutdown also cleans up running processes.

The `agent` mode supports tools, terminal access, and search. In headless operation, edits are proposed rather than applied unless auto-approval is enabled. `plan` and `ask` are read-only modes: the former develops a plan, while the latter explores without modifying files.

## Setup and configuration

Install Node.js 22 or newer, install the Cursor CLI, and authenticate it with `agent login`. The cursor-mcp MCP server can be launched with `npx -y @qmediat.io/cursor-mcp`, or installed globally to provide the `cursor-mcp` command. Claude Code and Claude Desktop configurations use an MCP server entry with the package as a stdio command. Local development can instead launch the built `dist/index.js` file with Node.

Optional environment variables control process behavior:

- `CURSOR_MAX_CONCURRENCY` sets the concurrent-process limit from 1 to 64; the default is 3.
- `CURSOR_ALLOW_YOLO=true` adds Cursor’s `--force` option for agent and reply calls. This permits automatic approval and should be restricted to trusted environments.
- `CURSOR_SANDBOX=enabled` or `disabled` selects Cursor’s sandbox setting. Invalid values stop startup.
- `CURSOR_KILL_GRACE_MS` sets the delay between termination signals, defaulting to 5,000 milliseconds.

## Limitations and notes

The Cursor CLI must already be installed and authenticated, and the account must include agent usage. The server does not store credentials; Cursor handles OAuth. It also does not make HTTP requests itself beyond activity performed by `cursor-agent`.

Every call trusts the supplied workspace, or the server’s current directory when none is provided. Use workspace paths only for directories intended for agent access. Auto-approval is controlled by the operator’s environment rather than an MCP tool argument, so an agent cannot enable it through a request. Enabling it can allow changes or commands; the sandbox is recommended for trusted automated runs.

Session listings cover the current server instance. On Windows, cleanup signals only the Cursor process itself rather than a POSIX process group. The `plan` mode cannot answer a clarifying question in headless operation.

_Full upstream README: https://allmcps.com/mcp/cursor-mcp/readme_