cursor-api-mcp

MCP server for the Cursor HTTP APIs.

By default the server exposes read and write tools (Cloud Agents + Team/Org Admin + Analytics + Bugbot + AI Code Tracking + Fleet). Pass --read-only (or set CURSOR_API_READ_ONLY=true) to register only fetch/query tools.

Install

git clone https://github.com/PhillipChaffee/cursor-api-mcp.git
cd cursor-api-mcp
uv sync

Create an API key at cursor.com/dashboard/api.

Run

# Full access (read + write)
CURSOR_API_KEY=crsr_... uv run cursor-api-mcp

# Read-only (write tools are not registered)
CURSOR_API_KEY=crsr_... uv run cursor-api-mcp --read-only

# Same via env
CURSOR_API_KEY=crsr_... CURSOR_API_READ_ONLY=true uv run cursor-api-mcp

Cursor MCP config

Merge into ~/.cursor/mcp.json (do not replace existing servers).

Read-only (recommended default):

{
  "mcpServers": {
    "cursor-api": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/ABS/PATH/TO/cursor-api-mcp",
        "cursor-api-mcp",
        "--read-only"
      ],
      "env": {
        "CURSOR_API_KEY": "crsr_YOUR_KEY_HERE"
      }
    }
  }
}

Full read/write — omit --read-only / CURSOR_API_READ_ONLY:

{
  "mcpServers": {
    "cursor-api": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/ABS/PATH/TO/cursor-api-mcp",
        "cursor-api-mcp"
      ],
      "env": {
        "CURSOR_API_KEY": "crsr_YOUR_KEY_HERE"
      }
    }
  }
}

Reload MCP in Cursor Settings → MCP after editing.

Tools

Cloud Agents (all plans, user API key)

Tool	API
`get_api_key_info`	`GET /v1/me`
`list_models`	`GET /v1/models`
`list_repositories`	`GET /v1/repositories`
`list_agents` / `get_agent`	`GET /v1/agents`
`list_agent_runs` / `get_agent_run`	`GET /v1/agents/{id}/runs`
`stream_agent_run`	`GET /v1/agents/{id}/runs/{runId}/stream`
`get_agent_usage`	`GET /v1/agents/{id}/usage`
`list_agent_artifacts`	`GET /v1/agents/{id}/artifacts`
`download_agent_artifact`	`GET /v1/agents/{id}/artifacts/download`

Write (disabled with --read-only):

Tool	API
`create_agent`	`POST /v1/agents`
`create_agent_run`	`POST /v1/agents/{id}/runs`
`cancel_agent_run`	`POST .../runs/{runId}/cancel`
`archive_agent` / `unarchive_agent`	`POST .../archive` / `unarchive`
`delete_agent`	`DELETE /v1/agents/{id}`
`create_worker_token`	`POST /v1/sub-tokens`

Fleet / private workers (service-account key)

Tool	API
`list_private_workers`	`GET /v0/private-workers`
`get_fleet_summary`	`GET /v0/private-workers/summary`
`get_private_worker`	`GET /v0/private-workers/{id}`
`list_pending_pool_requests`	`GET /v0/private-workers/pending-requests`

Team Admin (Enterprise)

Tool	API
`list_team_members`	`GET /teams/members`
`get_audit_logs`	`GET /teams/audit-logs`
`get_daily_usage_data`	`POST /teams/daily-usage-data`
`get_spending_data`	`POST /teams/spend`
`get_usage_events`	`POST /teams/filtered-usage-events`
`list_team_repo_blocklists`	`GET /settings/repo-blocklists/repos`
`list_billing_groups` / `get_billing_group`	`GET /teams/groups`

Write:

Tool	API
`set_user_spend_limit`	`POST /teams/user-spend-limit`
`remove_team_member`	`POST /teams/remove-member`
`upsert_repo_blocklists` / `delete_repo_blocklist`	blocklist mutate
`create_billing_group` / `update_billing_group` / `delete_billing_group`	groups
`add_billing_group_members` / `remove_billing_group_members`	group members

Organization Admin (Enterprise org key)

Tool	API
`list_organization_members`	`GET /organizations/members`
`get_organization_pooled_usage`	`POST /organizations/pooled-usage`
`get_organization_usage_events`	`POST /organizations/filtered-usage-events`
`get_organization_daily_usage_data`	`POST /organizations/daily-usage-data`
`get_organization_spending_data`	`POST /organizations/spend`
`list_organization_groups` / `get_organization_group`	`GET /organizations/groups`
`list_organization_group_members`	`GET .../groups/{id}/members`

Write:

Tool	API
`sync_organization_team_memberships`	`POST /organizations/team-memberships/sync`
`add_organization_group_members`	`POST .../members/bulk-add`
`remove_organization_group_members`	`POST .../members/bulk-remove`

Analytics (Enterprise)

Tool	API
`get_team_analytics`	`GET /analytics/team/{metric}`
`get_analytics_by_user`	`GET /analytics/by-user/{metric}`

metric is allowlisted (e.g. agent-edits, tabs, dau, models, bugbot, bugbot-reviews, conversation-insights, …). See tool docstrings for the full lists.

AI Code Tracking (Enterprise, alpha)

Tool	API
`list_ai_code_commits`	`GET /analytics/ai-code/commits`
`download_ai_code_commits_csv`	`GET /analytics/ai-code/commits.csv`
`list_ai_code_changes`	`GET /analytics/ai-code/changes`
`download_ai_code_changes_csv`	`GET /analytics/ai-code/changes.csv`
`get_ai_code_commit_details`	`GET /analytics/ai-code/commits/{hash}`

Bugbot (Enterprise)

Tool	API
`list_bugbot_repos`	`GET /bugbot/repos`

Write:

Tool	API
`trigger_bugbot_review`	`POST /bugbot/review`
`update_bugbot_repo`	`POST /bugbot/repo/update`
`update_bugbot_user_access`	`POST /bugbot/user/update`

Safety

Prefer --read-only unless you need mutations.
Use the narrowest API key scope that covers your tools.
Never commit .env or paste API keys into chat / git.
/v1/repositories is rate-limited (~1/min); avoid polling loops.
create_worker_token redacts accessToken in tool results (mint raw JWTs outside MCP).
stream_agent_run buffers SSE until close/timeout — prefer get_agent_run for watches.
CSV download tools return the body as csv_text (can be large).

Development

uv sync --extra dev
uv run pytest

License

MIT

cursor-api-mcp

cursor-api-mcp

Install

Run

Cursor MCP config

Tools

Cloud Agents (all plans, user API key)

Fleet / private workers (service-account key)

Team Admin (Enterprise)

Organization Admin (Enterprise org key)

Analytics (Enterprise)

AI Code Tracking (Enterprise, alpha)

Bugbot (Enterprise)

Safety

Development

License

Latest Blog Posts

MCP directory API