cursor-agent-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cursor-agent-mcp Run cursor-agent to implement the new API endpoint and review the diff before applying."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
cursor-agent-mcp
El puente entre Claude Code y cursor-agent — worktrees aislados, jobs en segundo plano, multi-agente en paralelo, y traer los cambios de vuelta a tu repo con diff / bring_changes.
Reemplaza este flujo manual:
export PATH="$HOME/.local/bin:$PATH"
git worktree add <ruta-temporal> -b <rama> origin/main
cd <ruta-temporal> && ln -s <repo>/node_modules node_modules
cursor-agent -p --trust --force "<plan>" --output-format text
# ... revisar git diff, y recién ahí traer los cambios ......por 4-5 llamadas a herramientas MCP. Los logs largos y el texto del plan quedan en disco, no metidos en la conversación.
Índice
Related MCP server: Claude PM MCP
Instalación
git clone https://github.com/jguevara0923/mcp-cursor.git ~/Desktop/mcps/cursor-agent-mcp
curl https://cursor.com/install -fsS | bash # si no tenés el CLI de Cursor
cursor-agent login # interactivo, una sola vez
cd ~/Desktop/mcps/cursor-agent-mcp && npm install
claude mcp add cursor-agent -- node ~/Desktop/mcps/cursor-agent-mcp/src/server.jsVerificar:
claude mcp list # debe aparecer "cursor-agent"
node test/smoke-test.mjs # prueba rápida, no gasta cuotaLas herramientas aparecen como mcp__cursor-agent__<nombre> (ej.
mcp__cursor-agent__plan_run).
Para actualizar más adelante: git pull && npm install — no hace falta
volver a registrar el MCP.
Requisito | Chequeo |
Node.js ≥ 18.17 |
|
Git ≥ 2.5 |
|
|
|
Por qué existe
Aislamiento real: cursor-agent nunca toca tu working directory — corre en un
git worktreeaparte, con su propia rama.No bloquea: lanzar un agente devuelve un
job_idal toque. Podés lanzar varios en paralelo y seguir trabajando.Ahorra tokens: por default solo ves un tail corto del log (~30 líneas). El log completo vive en disco.
Revisar antes de traer:
diffmuestra qué cambió sin tocar nada;bring_changesrecién ahí aplica el diff congit apply(nunca merge/rebase).
El flujo
flowchart LR
A["Vos + Claude Code\narmás el plan"] -->|"plan_run(repo, plan)"| B["cursor-agent\nComposer, etc."]
B -->|"corre en su propio\nworktree + rama"| C["Worktree aislado\ntu repo NO se toca"]
C -.->|"diff() — revisá qué cambió"| A
C -->|"bring_changes()\nrecién ahí se aplica"| D["Tu repo real"]
style A fill:#D97757,stroke:#3a3a3a,color:#fff
style B fill:#111111,stroke:#3a3a3a,color:#fff
style C fill:#6a48bf,stroke:#3a3a3a,color:#fff
style D fill:#2ea44f,stroke:#3a3a3a,color:#fffEjemplo real
// 1. Lanzar (repo_path real, no placeholder)
plan_run({
"repo_path": "/Users/joseguevara/Desktop/plaxp/backend",
"plan": "Agregar GET /api/reportes/compras/historico-por-producto/resumen, patrón hexagonal de reportes-compras",
"label": "historico-compras-resumen"
})
// -> { worktree: { worktreePath: "...", branch: "cursor-historico-compras-resumen-..." },
// job: { id: "20260922-031501-a1b2c3", status: "starting" } }
// 2. Esperar
job_wait({ "job_id": "20260922-031501-a1b2c3" })
// -> { status: "done", exitCode: 0, tail: "...últimas líneas del log..." }
// 3. Revisar (barato en tokens)
diff({ "worktree_path": "...", "stat_only": true })
// -> " .../get-historico-compras-por-producto.use-case.ts | 45 +++++++"
// 4. Traer, si se ve bien
bring_changes({ "worktree_path": "...", "target_repo_path": "/Users/joseguevara/Desktop/plaxp/backend" })
// 5. Limpiar
worktree_remove({ "repo_path": "/Users/joseguevara/Desktop/plaxp/backend", "worktree_path": "...", "delete_branch": "cursor-historico-compras-resumen-..." })Multi-agente (tareas independientes en paralelo, cada una en su propio worktree — nunca se pisan):
plan_run_parallel({
"tasks": [
{ "repo_path": "/Users/joseguevara/Desktop/plaxp/frontend", "label": "fix-producto-autocomplete", "plan": "..." },
{ "repo_path": "/Users/joseguevara/Desktop/plaxp/frontend", "label": "chart-comparativo-costos", "plan": "..." }
]
})
// -> { launched: 2, results: [{ label, worktree, job }, { label, worktree, job }] }Herramientas
Llamá help para un cheatsheet corto sin salir de la conversación.
Herramienta | Qué hace |
| Diagnóstico: cursor-agent instalado, versión, sesión logueada. |
| Modelos disponibles para |
| Worktree + rama nueva desde |
| Listar / borrar worktrees. |
| Primitivo: corre cursor-agent en un |
|
|
|
|
| Estado + tail corto del log. |
| Bloquea hasta que el job termine. |
| Log completo, paginado — solo si |
| Listar jobs / matar uno que sigue corriendo. |
| Qué cambió en el worktree ( |
| Aplica el diff a tu repo real con |
| Cheatsheet de todo esto. |
Parámetros más usados de run / plan_run / plan_run_parallel: plan o
plan_file (mejor para planes largos), model, mode (agent lee y
escribe; plan/ask son solo lectura), wait (default false — async),
label.
Diseño y límites
Los argumentos de
cursor-agent/gitvan siempre como array aspawn(), nunca como string armado a mano — el plan puede traer comillas o$sin riesgo.El entorno pasa una vez por una shell de login (cacheado) para heredar
PATH/variables de~/.zshrc.bring_changesusagit apply, nunca merge/rebase. Si el patch no aplica limpio, no toca nada.cursor-agenttiene worktrees nativos (-w/--worktree-base); este MCP usa los suyos propios para controlar elbase, la ruta y el symlink denode_modules.job_cancelsolo funciona en la sesión del server que lanzó ese job (el proceso vive en memoria, no en disco).Sin límite propio de jobs concurrentes — usá criterio con tu cuota de Cursor.
.jobs/crece con cada corrida; borrala entera si se hace grande (no afecta jobs en curso).
Estructura
cursor-agent-mcp/
src/
server.js # registro de herramientas MCP
cursorRunner.js # arma args y lanza cursor-agent
jobs.js # persistencia en .jobs/<id>/
worktree.js # worktree add/remove/list + diff + bring_changes
util.js # shell env cacheado, helpers
test/
smoke-test.mjs # sin gastar cuota
e2e-test.mjs # flujo completo en repo descartable
.jobs/ # (se crea solo) logs y metadataAvailable Tools
16 toolsbring_changesA
Aplica los cambios (sin commitear) de un worktree al working tree de tu repo real, vía git apply — NUNCA hace merge/rebase de historia, solo mueve el diff. Revisá con diff primero. Si algo no aplica limpio, no toca nada y te devuelve el error de git tal cual.
Inputs: worktree_path (required), target_repo_path (required), paths, stage.
checkA
Diagnóstico: verifica que el CLI cursor-agent esté instalado, su versión, y si CURSOR_API_KEY está disponible en el entorno de login shell. Corré esto primero si algo falla raro.
Inputs: no named parameters.
diffA
Diff de lo que cursor-agent cambió en un worktree (incluye archivos nuevos). Usalo para REVISAR antes de bring_changes — no trae nada al repo, solo muestra.
Inputs: worktree_path (required), paths, stat_only.
helpA
Cheatsheet compacto de este MCP: flujo típico, todas las herramientas y para qué sirve cada una. Llamá esto si no te acordás cómo se usa — más barato que leer el README completo.
Inputs: no named parameters.
job_cancelA
Mata el proceso de un job que sigue corriendo (SIGTERM). Solo funciona si el job fue lanzado por ESTA sesión del server (el handle del proceso es en memoria).
Inputs: job_id (required).
job_listA
Lista jobs (más nuevos primero), opcionalmente filtrados por repo_path o status. Compacto — sin log, solo metadata.
Inputs: limit, status, repo_path.
job_logA
Trae una porción del log completo de un job, paginado por líneas — usalo cuando el tail de job_status no alcanza para diagnosticar algo. No devuelvas esto por default; solo cuando de verdad haga falta más detalle (consume más tokens que job_status).
Inputs: job_id (required), from_end, limit_lines, offset_lines.
job_statusA
Estado actual de un job: running/done/failed/cancelled, exit code, duración, y las últimas líneas del log (tail chico por default — para más, usá job_log).
Inputs: job_id (required), tail_lines.
job_waitB
Bloquea hasta que un job termine (o se cumpla timeout_seconds) y devuelve el resultado final con el log completo (o su tail). Usalo después de run/plan_run con wait:false cuando ya querés el resultado.
Inputs: job_id (required), tail_lines, timeout_seconds.
list_modelsA
Lista los modelos disponibles para --model (ej. gpt-5, sonnet-4-thinking, claude-opus-4-8[...]).
Inputs: no named parameters.
plan_runB
Atajo todo-en-uno: crea el worktree Y lanza cursor-agent con el plan, en una sola llamada. Es el flujo recomendado para "dale este plan a Cursor". Async por default (wait:false) — devuelve worktree + job_id al toque.
Inputs: repo_path (required), base, mode, plan, +8 more.
plan_run_parallelA
Despliega VARIOS agentes de cursor-agent en paralelo, cada uno en su propio worktree/rama. Ideal para tareas independientes (ej. "arreglar bug A" y "agregar feature B" al mismo tiempo, sin que se pisen). Cada tarea es como un plan_run individual.
Inputs: tasks (required), wait, timeout_seconds.
runA
Lanza cursor-agent con un prompt/plan en un directorio dado. Por DEFAULT es asíncrono: devuelve un job_id al toque y sigue corriendo en segundo plano (usá job_status/job_wait para seguirlo) — así podés lanzar varios en paralelo sin bloquear. Pasá wait:true si preferís esperar a que termine y recibir el resultado directo.
Inputs: cwd (required), mode, wait, force, +11 more.
worktree_createA
Crea un git worktree aislado (+ rama nueva) para que cursor-agent trabaje sin tocar tu working directory actual. Hace git fetch del remoto de base primero. Si el repo es Node/TS, symlinkea node_modules del repo original (no reinstala nada).
Inputs: branch (required), repo_path (required), base, fetch, +2 more.
worktree_listA
Lista los worktrees activos de un repo (rutas + rama + HEAD).
Inputs: repo_path (required).
worktree_removeA
Elimina un worktree (y opcionalmente su rama). Usalo para limpiar después de traer los cambios con bring_changes, o para descartar un intento que no sirvió.
Inputs: repo_path (required), worktree_path (required), force, delete_branch.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Each tool has a clear, distinct purpose: environment checks, model listing, worktree management, running tasks (including combined and parallel variants), applying changes, diffing, and job lifecycle management. While some tools like job_status, job_wait, and job_log overlap in domain, their descriptions clearly differentiate status, blocking wait, and log retrieval.
Naming is mixed: some tools use verb_noun (list_models, bring_changes), others use noun_verb (worktree_create, job_status), and a few are simple verbs (check, run, help, diff). The pattern is not consistent, though the names remain readable and domain-appropriate.
16 tools is well-scoped for the purpose of orchestrating cursor-agent tasks in isolated worktrees with job management. Each tool serves a distinct role without redundancy, fitting comfortably within the 3-15 tool range.
The tool set covers the full lifecycle: environment verification, model selection, worktree creation/listing/removal, task execution (single, combined, parallel), change review (diff), change application (bring_changes), and comprehensive job management (status, wait, log, list, cancel). There are no obvious gaps that would hinder the workflow.
Maintenance
Related MCP Connectors
Shared work memory for Claude Code, Codex, Cursor and chat, scoped to each repository.
Git collaboration for AI agents and people: tasks, hand-offs, reviews, teams, shared memory.
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Shared long-term memory & Stop-hook task handoff across Claude Code, Codex, Cursor, and mobile.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables Claude to create, manage, and clean up git worktrees automatically, including dependency installation and GitHub PR creation.5MIT
- AlicenseNot gradedqualityCmaintenanceTurns Claude Code into an engineering project manager by orchestrating feature development with isolated Git worktrees, structured task validation, and approval-gated integration.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude Code to delegate tasks to Cursor's headless agent, run adversarial reviews, and verify findings with prosecutor/advocate roles.MIT
- AlicenseNot gradedqualityBmaintenanceEnables Claude Code, Codex, and Cursor to delegate self-contained coding tasks to one another on the user's own subscriptions, with each task isolated in a git worktree and sandbox, usage tracked, budgets enforced, and results returned for review.179 npm3Apache 2.0