Cursor MCP

An MCP server that lets Claude Code, Codex, and Grok launch and manage Cursor Cloud Agents. Choose which repositories they can access, launch a task, follow up, and inspect the reported branch or PR.

No policy means read-only; enabling launches is an explicit step. This is an independent project, not an official Cursor product.

You: Fix the empty-search bug in ExampleOrg/ExampleRepo, starting 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

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.

Source installation only; the npm package is not published yet.

1. Build the server

git clone https://github.com/ebrindley/cursor-mcp.git
cd cursor-mcp
npm ci
npm run build
node dist/bin.js --version

The last command prints the package version, with +unknown for an unstamped source build. It needs no credential. Keep this checkout at a stable path; your client will launch its dist/bin.js.

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. Enable one repository

Replace ExampleOrg/ExampleRepo with a repository your Cursor account can access:

node dist/bin.js setup --repo ExampleOrg/ExampleRepo
node dist/bin.js doctor

By default, setup creates ~/.config/cursor-mcp/policy.json without storing credentials or replacing an existing file. The policy enables launch, follow-up, cancellation, and everyday reads for that repository; it excludes deletion and environment operations. Real launches may incur Cursor charges.

Doctor should report OK for runtime, policy, credential, account, and repositories. It checks access without launching work. For existing policies, custom paths, or failed checks, see setup and diagnostics.

4. Register your client

Follow the configuration for your client:

Claude Code · Codex · Grok · Cursor

Use absolute paths to your Node executable and this checkout's 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 Cursor 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 Cursor 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.

Replace OWNER/REPO with the repository enabled above. A successful launch returns agent and run IDs; continue checking the run until it finishes. The policy requests automatic PR creation, but a run may finish without a PR. Inspect any reported branch or PR before deciding what to do next.

For a follow-up: "Ask that same Cursor 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

Report bugs through GitHub Issues. This is an independently maintained project; external pull requests are not accepted. Maintainer pull requests are used for the project's own development workflow. 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.