Cursor MCP

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.