108 lines
2.7 KiB
Markdown
108 lines
2.7 KiB
Markdown
# cursor-mcp
|
|
|
|
MCP server for Hermes (and other MCP clients) to delegate coding tasks to **Cursor** via the [Cursor SDK](https://cursor.com/docs/sdk/python).
|
|
|
|
## 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
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```bash
|
|
CURSOR_API_KEY=your-key-here
|
|
```
|
|
|
|
### 3. Register with Hermes
|
|
|
|
```bash
|
|
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](docs/CONFIGURATION.md).
|
|
|
|
### 4. Verify
|
|
|
|
```bash
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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](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
|
|
|
|
```bash
|
|
.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
|