nearxos
1d71b3f822
Surface Cursor run progress to stderr and response payloads, enforce CURSOR_TIMEOUT_SECONDS, validate git repos before delegate, and fix resume session cwd persistence. Includes docs, tests, and packaging. Co-authored-by: Cursor <cursoragent@cursor.com>
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 +
progressarray 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/python -m unittest discover -s tests -v
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