# Cursor Agent MCP Server

An MCP (Model Context Protocol) server that wraps the [Cursor CLI agent](https://cursor.com), enabling Claude Code and other MCP clients to delegate tasks to Cursor's AI agent.

## Features

- **cursor_agent** - Execute tasks with full Cursor agent capabilities (file writing, bash commands, etc.)
- **cursor_plan** - Read-only planning mode to design approaches before coding
- **cursor_ask** - Read-only Q&A mode for questions about the codebase
- **cursor_status** - Check Cursor agent authentication status
- **cursor_resume** - Resume previous Cursor agent conversations

## Prerequisites

1. Install the Cursor CLI agent:
   ```bash
   curl https://cursor.com/install -fsS | bash
   ```

2. Authenticate:
   ```bash
   agent login
   ```

3. Install Python dependencies:
   ```bash
   pip install fastmcp
   ```

## Usage

### With Claude Code

Add to your Claude Code MCP configuration (`~/.claude.json` or project settings):

```json
{
  "mcpServers": {
    "cursor-agent": {
      "command": "python",
      "args": ["/path/to/cursor_mcp_server.py"],
      "env": {
        "CURSOR_WORKSPACE_PATH": "/path/to/your/workspace"
      }
    }
  }
}
```

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `CURSOR_WORKSPACE_PATH` | Default working directory for agent tasks | `~` |
| `CURSOR_AGENT_PATH` | Path to the cursor agent executable | `agent` |
| `CURSOR_DEFAULT_TIMEOUT` | Default timeout in seconds | `300` |
| `CURSOR_DEFAULT_MODEL` | Default model for agent tasks | `gpt-5.2-codex-xhigh` |

### Running Standalone

```bash
python cursor_mcp_server.py
```

## Tool Reference

### cursor_agent

Execute tasks with full agent capabilities.

```python
cursor_agent(
    prompt="Implement a login form with validation",
    workspace="/path/to/project",  # optional
    force=True,  # allow file modifications
    timeout=300,  # seconds
    model="gpt-5.2-codex"  # optional model override
)
```

### cursor_plan

Design an approach before implementing.

```python
cursor_plan(
    prompt="How should I refactor the authentication system?",
    workspace="/path/to/project"
)
```

### cursor_ask

Ask questions about the codebase.

```python
cursor_ask(
    prompt="What does the DatabaseManager class do?",
    workspace="/path/to/project"
)
```

### cursor_resume

Resume a previous conversation.

```python
cursor_resume(
    prompt="Continue with the next step",
    session_id="abc123",  # optional, omit for latest session
    workspace="/path/to/project"
)
```

## License

MIT