Skip to main content
Glama
Sign In
cursor-mcp

cursor-mcp

by ebrindley
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Cursor Cloud Agents & VMs

See the waiting standard for deadlines, cancellation, and resuming accepted work.

An MCP server that lets Claude Code, Codex, and Grok launch and manage Cursor Cloud Agents, use their VM terminals, and manage associated environments. It is not a general local coding or research runner. Choose which repositories cloud agents can access, launch a task, follow up, and inspect the reported branch or PR.

This is an independent project, not an official Cursor product.

You: Use a Cursor Cloud Agent to fix the empty-search bug in ExampleOrg/ExampleRepo.
     Start from main.
     Open a PR, report the result, and leave merging to me.
Assistant: Launches a scoped cloud agent and keeps its agent/run IDs.
You: Check its progress, then ask the same agent to cover whitespace-only input.
Assistant: Reads the run and sends a follow-up to the existing agent.

This illustrates the interaction; your assistant chooses its wording. For a runnable example with simulated Cursor responses, try npm run demo after building. It exercises real MCP handlers, including a refused out-of-scope launch, without network requests or a key. See the offline walkthrough.

Quickstart · Client setup · Troubleshooting · Documentation

Local Cursor or Cloud Agents?

This integration manages Cursor Cloud Agents, not local Cursor sessions. A new repository-backed Cloud Agent does not automatically receive local-only files or unpushed changes. See execution context for local/cloud selection and tool authority.

Related MCP server: Cloud Agent MCP Server

Quickstart

You need:

  • Git and Node.js 24 LTS, including npm. See runtime compatibility for other supported versions.

  • A Cursor account with an API key and access to the repository you want to use.

  • Claude Code, Codex, Grok, or Cursor as your MCP client.

Installation uses GitHub source and automates dependency installation and building. Without a policy file, the server is read-only. On a fresh installation, the installer creates an account-wide policy for agent management and terminal access across repositories and environments your Cursor account can access. Deletion tools are excluded, and existing policies are preserved. For narrower access, see restricted profiles before launching work.

1. Install the server

curl -fsSL https://raw.githubusercontent.com/ebrindley/cursor-mcp/main/scripts/install.sh | bash -s -- install

The installer checks prerequisites and offers to install or update. It builds and verifies a separate release before activating it, retaining the previous release. The default installation is ~/.local/share/cursor-mcp; CURSOR_MCP_ROOT overrides it. See installation and updates for client selection and local pinning.

2. Provide your API key

Create a Cursor API key and export it as CURSOR_API_KEY in the terminal where you will run doctor and start your CLI client. Keep the key out of this checkout and shared configuration. The server does not load .env files itself. Desktop clients may need their own environment configuration.

3. Check setup

Run the installation check:

node ~/.local/share/cursor-mcp/current/dist/bin.js doctor

Read the reported permissions and confirm that they match your intended use. No model is pinned by default. For restricted profiles, policy migration and model selection, see capability setup.

4. Connect your client

The installer registers detected Claude Code, Codex and Grok clients during installation. To select clients explicitly or add one later, rerun it with install --host claude (or codex / grok). Cursor registration requires install --with-cursor.

For manual registration or configuration details, see:

Claude Code · Codex · Grok · Cursor

Use absolute paths to your Node executable and the installation's current/dist/bin.js. Restart the client after registration or policy changes. For CLI clients, start it from the terminal where CURSOR_API_KEY is exported.

5. Verify the connection

Ask your connected assistant:

Use the Cursor Cloud Agent integration to list the repositories I can access. Do not launch an agent.

Success means the assistant calls cursor_list_repos and returns repository information without a connection or authentication error. Confirm your intended repository is available. Doctor alone does not verify MCP client registration; see troubleshooting if this check fails.

6. Try your first task

Use a Cursor Cloud Agent to fix a small bug in OWNER/REPO, starting from main. State the target before launching. Keep the returned agent and run IDs. Check the result and report any returned PR link and remaining work. Do not merge it.

Real launches may incur Cursor charges. Replace OWNER/REPO with the intended repository available to your account and permitted by your policy. A successful launch returns agent and run IDs; continue checking the run until it finishes. The task asks for a PR, but a run may finish without one. Inspect any reported branch or PR before deciding what to do next.

For a follow-up: "Ask that same Cursor Cloud Agent to add the missing regression test." See the first-task guide for examples and resuming after a restart.

Capabilities and limits

  • Launch cloud agents, read their runs and artifacts, send follow-ups, and cancel work. Operator-owned profiles control repositories, environments, and tools; deletion requires a separate grant.

  • Optional activity excerpts support resume cursors; they do not provide continuous UI progress. See the activity guide.

  • Advanced environment diagnostics are opt-in. Some launch paid cloud work or require an explicitly configured Cursor CLI. Unsupported operations report the owner action still needed; coverage does not include every Cursor API operation or fully automatic environment management.

Documentation

Support and security

Bug reports are welcome through GitHub Issues. This is an independently maintained project. Pull requests are not accepted. Support, response times, and fixes are not guaranteed.

Report vulnerabilities privately through GitHub's vulnerability reporting form. Keep vulnerability details and credentials out of public issues.

License

MIT. You may fork, modify, and redistribute the project, including for commercial use.

Available Tools

23 tools
cursor_assess_environment_healthCursor: assess environment health and freshnessA
Read-onlyIdempotent

Judge Build health, source drift, and toolchain drift from readback you hold. Launches nothing and returns a scheduler exit code.

Inputs: environmentPublicId (required), asOfMs, builds, baseline, +4 more. Returns: build, state, reason, source, +8 more

cursor_diff_environment_definitionCursor: diff environment definitionsA
Read-onlyIdempotent

Bounded semantic diff between two Cursor environment definitions. Scripts and MCP patterns are compared by digest, so no field value can leave through the diff.

Inputs: base (required), proposed (required). Returns: base, status, changes, proposed, +2 more

cursor_get_agentCursor: get agentA
Read-onlyIdempotent

Inspect one agent: repos, settings, web URL, and the id of its most recent run.

Inputs: agentId (required). Returns: id, url, name, repos, +8 more

cursor_get_artifact_urlCursor: get artifact download URLA
Read-onlyIdempotent

Mint a 15-minute presigned download URL for one artifact path from cursor_list_artifacts.

Inputs: path (required), agentId (required). Returns: url, expiresAt

cursor_get_environment_configurationCursor: get environment configurationA
Read-onlyIdempotent

Read one environment's configuration candidates, source, precedence, and digest through a configured Cursor CLI. Scripts stay digests.

Inputs: environmentPublicId (required). Returns: cli, reason, status, catalog, +3 more

cursor_get_runCursor: get runA
Read-onlyIdempotent

Inspect one run: status, duration, reported branch or PR, and the final reply once it has finished.

Inputs: runId (required), agentId (required). Returns: id, status, branches, terminal, +2 more

cursor_get_usageCursor: get usageA
Read-onlyIdempotent

Report an agent's token usage, totalled and broken down per run. Pass runId to scope it to one run.

Inputs: agentId (required), runId. Returns: runs, totalTokens, chargedCents

cursor_get_workspace_controlCursor: get workspace controlA
Read-onlyIdempotent

Read one workspace or account control. Supported controls fetch live; others return a capability result.

Inputs: control (required). Returns: id, kind, tool, repos, +10 more

cursor_inspect_environment_definitionCursor: inspect environment definitionA
Read-onlyIdempotent

Normalized view of a Cursor environment definition: install and start, terminals, ports, MCP policy, container build paths, and snapshot input. Scripts are digests.

Inputs: definition (required). Returns: trust, errors, origin, safety, +6 more

cursor_inspect_runsCursor: inspect several runsA
Read-onlyIdempotent

Read status for up to 64 agent/run id pairs you hold, in your order, under one 45s bound. Exact pairs only; continue at remaining.fromIndex unless complete.

Inputs: runs (required), fromIndex. Returns: items, checked, complete, fromIndex, +4 more

cursor_inspect_workspaceCursor: inspect workspaceA
Read-onlyIdempotent

Inspect API-key identity, entitlement, and the workspace-control surface. Does not list repositories.

Inputs: no named parameters. Returns: id, kind, tool, action, +9 more

cursor_list_agentsCursor: list agentsA
Read-onlyIdempotent

List cloud agents, newest first. Status is not execution state; use cursor_get_run.

Inputs: limit, prUrl, cursor, includeArchived. Returns: agents, nextCursor, unresolved

cursor_list_artifactsCursor: list artifactsA
Read-onlyIdempotent

List files an agent saved to its workspace artifacts directory. Code changes land on the branch, not here.

Inputs: agentId (required). Returns: artifacts

cursor_list_environmentsCursor: list environmentsA
Read-onlyIdempotent

List saved cloud environments through a configured Cursor CLI. Without one, reports why the authority is unavailable.

Inputs: scope. Returns: cli, reason, status, catalog, +3 more

cursor_list_modelsCursor: list modelsA
Read-onlyIdempotent

List model ids accepted when launching a cloud agent. Omit the model to use the account default.

Inputs: no named parameters. Returns: models

cursor_list_owner_actionsCursor: list owner actionsB
Read-onlyIdempotent

Catalog of Build and environment operations no supported authority performs: cancel, activate, deactivate, roll back, Restore, host-wide trigger. Returns the exact owner action for the ids you pass; launches nothing.

Inputs: action, buildId, supersededBuildId, environmentPublicId, +1 more. Returns: actions

cursor_list_reposCursor: list repositoriesA
Read-onlyIdempotent

List GitHub repositories Cursor can launch an agent against. Rate limited to one call per minute.

Inputs: no named parameters. Returns: repos

cursor_list_runsCursor: list runsB
Read-onlyIdempotent

List an agent's runs, newest first. Run status carries the execution state: CREATING, RUNNING, or a terminal value.

Inputs: agentId (required), limit, cursor. Returns: runs, nextCursor

cursor_list_workspace_controlsCursor: list workspace controlsA
Read-onlyIdempotent

List Cloud Agent workspace and account controls and whether each is supported, unverified, unsupported, or unavailable.

Inputs: kind, status. Returns: controls

cursor_tail_runCursor: recent run activityA
Read-onlyIdempotent

Read a bounded run activity excerpt. Pass lastEventId back to resume; without it Cursor replays from the beginning. Status is checked separately. Does not cancel the cloud run.

Inputs: runId (required), agentId (required), durationMs, lastEventId. Returns: done, status, terminal, bytesRead, +6 more

cursor_validate_environment_definitionCursor: validate environment definitionA
Read-onlyIdempotent

Check a Cursor environment definition against the published schema. Schema errors, safety warnings, and capability limitations are reported separately.

Inputs: definition (required), syncTarget. Returns: trust, errors, origin, safety, +6 more

cursor_wait_runCursor: wait for runA
Read-onlyIdempotent

Poll one run until it is terminal or waitMs elapses (default 30s, maximum 45s). Returns what cursor_get_run returns plus timedOut; call again to keep waiting.

Inputs: runId (required), agentId (required), waitMs, pollIntervalMs. Returns: id, polls, status, branches, +5 more

cursor_whoamiCursor: whoamiA
Read-onlyIdempotent

Verify the Cursor API key and return its name, creation date, and owning email.

Inputs: no named parameters. Returns: createdAt, userEmail, apiKeyName

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.8/5.0

    Scored across 23 tools

    Disambiguation4/5

    Most tools target distinct resources and actions, and the descriptions clearly separate list/get/inspect/wait/tail operations. A few clusters, especially around workspace controls and run inspection, could require close reading to pick the right tool, but none truly duplicate another.

    Naming Consistency5/5

    All tools use the consistent cursor_<verb>_<object> pattern with lowercase snake_case. The only minor deviation is cursor_whoami, but it is a conventional verb-like command and does not disrupt the overall consistency.

    Tool Count4/5

    23 tools is on the heavy side, but the domain is broad, covering identity, workspace controls, agents, runs, usage, artifacts, and environment definitions. Each tool has a distinct purpose, so the count feels slightly large rather than bloated.

    Completeness3/5

    The read/inspection side is thorough: identity, agents, runs, usage, artifacts, environment definitions, and health are well covered. However, there are no tools to launch, mutate, or cancel agents or runs, despite descriptions referencing launching cloud agents, and owner actions are only returned, not executed.

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Cloud Agent MCP Server

      jxnl
      A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to create and manage Cursor Cloud Agents that autonomously work on GitHub repositories, including creating tasks, monitoring progress, and automatically generating pull requests.
      14 npm
      7
      MIT

    • cursor-cloud-agent-mcp

      Tanya7z
      A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude to launch and manage Cursor Cloud Agents on GitHub repos, including polling status, sending follow-ups, and reading conversations/PRs.
      14 npm
      MIT