Cursor Cloud Agent MCP

🚀 Cloud Agent MCP Server

The MCP server for the Cursor Cloud Agents API. It enables AI assistants to create and manage cloud agents that operate on GitHub repositories.

🚀 Quick Start

# Install
npm install -g cursor-cloud-agent-mcp

# Set your API key
export CURSOR_API_KEY=your_api_key_here

# Use with Cursor (create .cursor/mcp.json)
{
  "mcpServers": {
    "cursor-cloud-agent": {
      "command": "npx",
      "args": ["-y", "cursor-cloud-agent-mcp"],
      "env": {
        "CURSOR_API_KEY": "${env:CURSOR_API_KEY}"
      }
    }
  }
}

✨ Features

• Enables AI assistants to manage cloud agents on GitHub repositories.
• Supports multiple client connections like Cursor, Claude Desktop, and MCP Inspector.
• Provides a variety of tools for task management and repository discovery.

📦 Installation

Install from npm

npm install -g cursor-cloud-agent-mcp

Or install locally in your project:

npm install cursor-cloud-agent-mcp

Install from Source

If you're developing or want to run from source:

# Clone and install dependencies
git clone https://github.com/jxnl/cursor-cloud-agent-mcp
cd cloud-agent-mcp
npm install

# Set your API key
export CURSOR_API_KEY=your_api_key_here

# Run HTTP server
npm start
# Server runs at http://localhost:3000/mcp

# Or run stdio server
npm run start:stdio

📚 Documentation

Configuration

Environment Variables

Connecting Clients

Cursor

Option 1: Using npm package (Recommended)

After installing via npm, create .cursor/mcp.json:

{
  "mcpServers": {
    "cursor-cloud-agent": {
      "command": "npx",
      "args": ["-y", "cursor-cloud-agent-mcp"],
      "env": {
        "CURSOR_API_KEY": "${env:CURSOR_API_KEY}"
      }
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "cursor-cloud-agent": {
      "command": "cursor-cloud-agent-mcp",
      "env": {
        "CURSOR_API_KEY": "${env:CURSOR_API_KEY}"
      }
    }
  }
}

Option 2: From source (Development)

If running from source, create .cursor/mcp.json:

{
  "mcpServers": {
    "cursor-cloud-agent": {
      "command": "npm",
      "args": ["run", "start:stdio"],
      "env": {
        "CURSOR_API_KEY": "${env:CURSOR_API_KEY}"
      }
    }
  }
}

Option 3: HTTP Server (Alternative)

If you prefer the HTTP version, configure it as:

{
  "mcpServers": {
    "cursor-cloud-agent": {
      "url": "http://localhost:3000/mcp",
      "headers": {}
    }
  }
}

Then run npm start in a separate terminal to start the HTTP server.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cloud-agent": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

MCP Inspector

npx @modelcontextprotocol/inspector
# Connect to http://localhost:3000/mcp

💻 Usage Examples

Typical Workflow

1. get_repos          → Get current repo URL and branch
2. create_task       → Launch task with prompt
3. get_task          → Check status (CREATING → RUNNING → FINISHED)
4. add_followup       → (optional) Send more instructions while running
5. get_conversation   → Review what the task did

Available Tools

Discovery Tools

Task Lifecycle Tools

Common Examples

Create a Task

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Add a README.md file with installation instructions",
    "repository": "https://github.com/your-org/your-repo",
    "auto_pr": true
  }
}

List Tasks

{
  "tool": "list_tasks",
  "arguments": {
    "filter": "FINISHED|RUNNING",
    "limit": 10
  }
}

Get Repository Info

{
  "tool": "get_repos"
}

🔧 Technical Details

Tool Documentation

get_repos - Get Repositories

Basic usage (current repo only):

{
  "tool": "get_repos"
}

Fetch all accessible repositories (filters REQUIRED):

Important: When using include_all: true, you MUST provide regex_patterns to filter the results. This prevents returning too many repositories.

Filter repositories with regex patterns:

{
  "tool": "get_repos",
  "arguments": {
    "include_all": true,
    "regex_patterns": ["^my-.*"]
  }
}

Multiple filter patterns (OR logic):

{
  "tool": "get_repos",
  "arguments": {
    "include_all": true,
    "regex_patterns": [".*api.*", ".*backend.*", ".*frontend.*"]
  }
}

Specify working directory:

{
  "tool": "get_repos",
  "arguments": {
    "working_directory": "/path/to/project"
  }
}

Filter Examples:

• ["^my-.*"] - Repos starting with "my-"
• [".*api.*"] - Repos containing "api"
• ["github.com/myorg"] - Repos from specific org
• [".*backend.*", ".*server.*"] - Repos matching either pattern

get_me - Verify Authentication

{
  "tool": "get_me"
}

get_models - List Available Models

{
  "tool": "get_models"
}

create_task - Launch a Cloud Task

Basic usage:

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Add a README.md file with installation instructions",
    "repository": "https://github.com/your-org/your-repo"
  }
}

With branch specification:

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Fix authentication bug",
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main"
  }
}

Auto-create PR:

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Add user authentication",
    "repository": "https://github.com/your-org/your-repo",
    "auto_pr": true
  }
}

Custom branch name:

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Implement new feature",
    "repository": "https://github.com/your-org/your-repo",
    "branch_name": "feature/new-feature"
  }
}

Specify model:

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Refactor codebase",
    "repository": "https://github.com/your-org/your-repo",
    "model": "claude-4-sonnet-thinking"
  }
}

With plan file:

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Implement the features described in the plan",
    "repository": "https://github.com/your-org/your-repo",
    "plan_file": "./plan.md"
  }
}

Complete example with all options:

{
  "tool": "create_task",
  "arguments": {
    "prompt": "Add comprehensive test coverage",
    "repository": "https://github.com/your-org/your-repo",
    "ref": "develop",
    "branch_name": "feature/add-tests",
    "auto_pr": true,
    "model": "o3",
    "plan_file": "./test-plan.md"
  }
}

list_tasks - List All Tasks

Basic listing:

{
  "tool": "list_tasks"
}

Limit results:

{
  "tool": "list_tasks",
  "arguments": {
    "limit": 10
  }
}

Pagination with cursor:

{
  "tool": "list_tasks",
  "arguments": {
    "limit": 20,
    "cursor": "bc_ghi789"
  }
}

Filter by status:

{
  "tool": "list_tasks",
  "arguments": {
    "filter": "FINISHED|RUNNING"
  }
}

Filter by repository:

{
  "tool": "list_tasks",
  "arguments": {
    "filter": ".*my-repo.*"
  }
}

Filter by branch name:

{
  "tool": "list_tasks",
  "arguments": {
    "filter": "feature/.*"
  }
}

Filter by summary content:

{
  "tool": "list_tasks",
  "arguments": {
    "filter": ".*README.*"
  }
}

Combine filters:

{
  "tool": "list_tasks",
  "arguments": {
    "filter": "FINISHED.*my-repo"
  }
}

Filter Examples:

• "FINISHED" - Only finished tasks
• "RUNNING|CREATING" - Active tasks
• ".*api.*" - Tasks working on API repos
• "feature/.*" - Tasks on feature branches
• "FINISHED.*README" - Finished tasks with README in summary
• "FAILED|CANCELLED" - Failed or cancelled tasks

get_task - Get Task Status

{
  "tool": "get_task",
  "arguments": {
    "id": "bc_abc123"
  }
}

add_followup - Send Follow-up Instructions

{
  "tool": "add_followup",
  "arguments": {
    "id": "bc_abc123",
    "prompt": "Also add a troubleshooting section"
  }
}

get_conversation - Get Conversation History

{
  "tool": "get_conversation",
  "arguments": {
    "id": "bc_abc123"
  }
}

delete_task - Delete a Task

{
  "tool": "delete_task",
  "arguments": {
    "id": "bc_abc123"
  }
}

Response Shapes

All tools return structured JSON responses matching the Cloud Agents API specification. See docs.md for complete API documentation.

get_me Response

{
  "apiKeyName": "Production API Key",
  "createdAt": "2024-01-15T10:30:00Z",
  "userEmail": "developer@example.com"
}

get_models Response

{
  "models": [
    "claude-4-sonnet-thinking",
    "o3",
    "claude-4-opus-thinking"
  ]
}

get_repos Response

{
  "current": {
    "repository": "https://github.com/your-org/your-repo",
    "branch": "main",
    "has_uncommitted_changes": false
  },
  "available": [
    {
      "owner": "your-org",
      "name": "your-repo",
      "repository": "https://github.com/your-org/your-repo"
    }
  ],
  "total_count": 1
}

create_task Response

{
  "id": "bc_abc123",
  "name": "Add README Documentation",
  "status": "CREATING",
  "source": {
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main"
  },
  "target": {
    "branchName": "feature/add-readme",
    "url": "https://cursor.com/agents?id=bc_abc123",
    "autoCreatePr": true,
    "openAsCursorGithubApp": false,
    "skipReviewerRequest": false
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

list_tasks Response

{
  "tasks": [
    {
      "id": "bc_abc123",
      "name": "Add README Documentation",
      "status": "FINISHED",
      "source": {
        "repository": "https://github.com/your-org/your-repo",
        "ref": "main"
      },
      "target": {
        "branchName": "cursor/add-readme-1234",
        "url": "https://cursor.com/agents?id=bc_abc123",
        "prUrl": "https://github.com/your-org/your-repo/pull/1234",
        "autoCreatePr": false,
        "openAsCursorGithubApp": false,
        "skipReviewerRequest": false
      },
      "summary": "Added README.md with installation instructions and usage examples",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "nextCursor": "bc_ghi789"
}

get_task Response

{
  "id": "bc_abc123",
  "name": "Add README Documentation",
  "status": "FINISHED",
  "source": {
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main"
  },
  "target": {
    "branchName": "cursor/add-readme-1234",
    "url": "https://cursor.com/agents?id=bc_abc123",
    "prUrl": "https://github.com/your-org/your-repo/pull/1234",
    "autoCreatePr": false,
    "openAsCursorGithubApp": false,
    "skipReviewerRequest": false
  },
  "summary": "Added README.md with installation instructions and usage examples",
  "createdAt": "2024-01-15T10:30:00Z"
}

Status Values: CREATING, RUNNING, FINISHED, FAILED, CANCELLED

get_conversation Response

{
  "id": "bc_abc123",
  "messages": [
    {
      "id": "msg_001",
      "type": "user_message",
      "text": "Add a README.md file with installation instructions"
    },
    {
      "id": "msg_002",
      "type": "assistant_message",
      "text": "I'll help you create a comprehensive README.md file..."
    }
  ]
}

add_followup Response

{
  "id": "bc_abc123"
}

delete_task Response

{
  "id": "bc_abc123"
}

Advanced

Plan Parallel Tasks

Use /plan-parallel-tasks to break down a project for multiple parallel tasks:

/plan-parallel-tasks
project_description: "Add user authentication with login, signup, and password reset"

This will:

1. Call get_repos to detect your repository
2. Break the project into independent tasks
3. Group tasks into phases (parallel → sequential)
4. Provide exact prompts for each create_task call

Parallelization Rules

CAN run in parallel:

• Tasks that modify completely different files
• Tasks that create new files without touching shared files

CANNOT run in parallel:

• Tasks that modify the same file
• Tasks where one depends on another's output
• Tasks that both modify package.json, tsconfig.json, etc.

Server Versions

This package includes two server versions:

• HTTP Server (src/server.ts): Runs an Express HTTP server on port 3000. Use for remote connections or when you need HTTP endpoints.
• Stdio Server (src/server-stdio.ts): Uses standard input/output. Recommended for local integrations. Better for process-based spawning.

Run with:

• HTTP: npm start (default)
• Stdio: npm run start:stdio

Development

Health Check

The server exposes a health check endpoint:

curl http://localhost:3000/health

Returns: {"status":"ok","service":"cursor-cloud-agent-mcp","version":"1.0.2"}

Publishing to npm

To publish this package to npm:

# Make sure you're logged in
npm login

# Publish
npm publish

The package will be available as cursor-cloud-agent-mcp on npm.

📄 License

MIT