cursor-mcp

MCP server for Hermes (and other MCP clients) to delegate coding tasks to Cursor via the Cursor SDK.

Features

• Delegate one-shot coding tasks (cursor_delegate)
• Session + resume for multi-step work (cursor_delegate_session, cursor_resume)
• Progress streaming to stderr + progress array in responses
• Timeout enforcement via CURSOR_TIMEOUT_SECONDS
• Git validation before delegate (configurable)
• Session index for follow-up work

Quick start

1. Install

cd ~/Projects/cursor-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

2. Configure API key

Create a user API key in Cursor Dashboard → API Keys, then add to ~/.hermes/.env:

CURSOR_API_KEY=your-key-here

3. Register with Hermes

hermes mcp add cursor \
  --command ~/.hermes/mcp_servers/cursor-mcp-env.sh \
  --env CURSOR_DEFAULT_CWD=/Users/you/Projects \
  --env CURSOR_DEFAULT_MODEL=composer-2.5 \
  --timeout 1900

Or add manually to ~/.hermes/config.yaml — see docs/CONFIGURATION.md.

4. Verify

hermes mcp test cursor

MCP tools

Tool	Use when
cursor_delegate	One-shot task (bug fix, small change)
cursor_delegate_session	Multi-step work; returns agent_id
cursor_resume	Follow-up on existing Cursor session
cursor_test_connection	Verify API key + project path
cursor_list_sessions	Recent delegations with agent_id
cursor_get_config	Non-secret config + recent sessions

Response shape (v1.1+)

Delegation tools return JSON including:

{
  "status": "finished",
  "run_id": "...",
  "agent_id": "...",
  "result": "...",
  "duration_ms": 64200,
  "git": {"branch": "main", "commit": "abc1234", "dirty": false},
  "progress": [
    {"kind": "status", "message": "running"},
    {"kind": "delta", "message": "started edit_file", "tool": "edit_file"}
  ]
}

Live progress also appears on stderr as [cursor-mcp] ... (Hermes: ~/.hermes/logs/mcp-stderr.log).

Configuration

See docs/CONFIGURATION.md for all CURSOR_* environment variables.

Hermes skill

Use the cursor-delegation skill in the senior-coder profile for prompt templates and orchestration patterns.

Development

.venv/bin/pip install -e .
.venv/bin/python -m unittest discover -s tests -v

Repository: https://git.paraskeva.net/nearxos/cursor-mcp

Notes

• Runs Cursor's local agent loop against files on disk — does not control the open Cursor IDE window.
• Billing follows your Cursor plan (SDK usage).
• Node.js 22+ is required by the Cursor SDK runtime.

License

MIT