# cursor-cloud-agent-mcp

MCP server that exposes the [Cursor Cloud Agent API](https://cursor.com/docs/cloud-agent/api/endpoints) as native tools for Claude Desktop, Claude Code, and any MCP-compatible client. Lets Claude launch Cursor agents on your GitHub repos, poll their status, send follow-ups, and read the resulting conversation/PR.

## Tools

| Tool | Purpose |
|---|---|
| `cursor_list_models` | List models available to Cursor Cloud Agents |
| `cursor_launch_agent` | Launch an agent on a repo (optional `auto_wait` blocks until done) |
| `cursor_get_agent` | Peek an agent's current status |
| `cursor_wait_agent` | Block until the agent reaches a terminal state or timeout |
| `cursor_followup_agent` | Send a follow-up message to a running agent |
| `cursor_get_conversation` | Read the full message history of an agent |

The two launch modes — `auto_wait: true` (one call does the whole job) and `auto_wait: false` (launch + poll separately) — let the calling LLM choose between "do it now and report back" vs "kick off then keep planning."

## Prerequisites

- Node.js ≥ 20
- A Cursor Cloud Agent API key from [cursor.com/cloud-agent](https://cursor.com/cloud-agent) (starts with `crsr_`)

## Install

```bash
cd cursor-cloud-agent-mcp
npm install
npm run build
```

## Run

The server speaks JSON-RPC over stdio — don't run it directly; let your MCP client launch it.

```bash
CURSOR_API_KEY=crsr_xxxxxxxxxxxxxxxxxx node dist/index.js
```

## Wire into Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "cursor": {
      "command": "node",
      "args": ["<absolute-path>/cursor-cloud-agent-mcp/dist/index.js"],
      "env": {
        "CURSOR_API_KEY": "crsr_xxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

Then restart Claude Desktop. You'll see the `cursor_*` tools in the tool picker.

## Wire into Claude Code

Add to `.mcp.json` in your project root or `~/.claude/.mcp.json` globally:

```json
{
  "mcpServers": {
    "cursor": {
      "command": "node",
      "args": ["<absolute-path>/cursor-cloud-agent-mcp/dist/index.js"],
      "env": { "CURSOR_API_KEY": "crsr_xxxxxxxxxxxxxxxxxx" }
    }
  }
}
```

## Example conversation

> **You:** Use Cursor to add a "build status" badge to the README of `myorg/myrepo`, on branch `main`, using Sonnet. Block until it's done and tell me the PR URL.

> **Claude:** *(calls `cursor_launch_agent` with `auto_wait: true`)* Done — PR opened at https://github.com/myorg/myrepo/pull/42.

## Development

```bash
npm run dev    # tsx — runs src/index.ts directly, no build step
npm run build  # tsc — produces dist/
```

Inspect with the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

## How it works

- `src/cursorClient.ts` — fetch wrapper, HTTP Basic auth, retry idempotent GETs on transient failures
- `src/polling.ts` — `waitForAgent` polls until terminal status or timeout; respects AbortSignal
- `src/tools/*.ts` — six tool handlers, each with a zod input schema
- `src/server.ts` — wires tools into `@modelcontextprotocol/sdk` Server + StdioServerTransport

## Limitations

- Cursor's API is request/response, not streaming — long outputs return in one MCP content block
- POSTs (launch agent, follow-up) are **not** auto-retried by the client to avoid double-launching
- Polling intervals default to 7s; very long tasks (>30 min) need multiple `cursor_wait_agent` calls

## License

MIT