cursor-cloud-agent-mcp

MCP server that exposes the Cursor Cloud Agent API 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 (starts with crsr_)

Install

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.

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):

{
  "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:

{
  "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

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

Inspect with the MCP Inspector:

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