Skip to main content
Glama

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.

Claude Code cursor-agent Node.js MCP License: MIT


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.js

Verificar:

claude mcp list          # debe aparecer "cursor-agent"
node test/smoke-test.mjs # prueba rápida, no gasta cuota

Las 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

node --version

Git ≥ 2.5

git --version

cursor-agent logueado

cursor-agent status

Por qué existe

  • Aislamiento real: cursor-agent nunca toca tu working directory — corre en un git worktree aparte, con su propia rama.

  • No bloquea: lanzar un agente devuelve un job_id al 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: diff muestra qué cambió sin tocar nada; bring_changes recién ahí aplica el diff con git 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:#fff

Ejemplo 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

check

Diagnóstico: cursor-agent instalado, versión, sesión logueada.

list_models

Modelos disponibles para model.

worktree_create

Worktree + rama nueva desde base (default origin/main). Symlinkea node_modules.

worktree_list / worktree_remove

Listar / borrar worktrees.

run

Primitivo: corre cursor-agent en un cwd. Async por default.

plan_run

worktree_create + run en un paso — el que usás normalmente.

plan_run_parallel

plan_run varias veces a la vez, un worktree por tarea.

job_status

Estado + tail corto del log.

job_wait

Bloquea hasta que el job termine.

job_log

Log completo, paginado — solo si job_status no alcanza.

job_list / job_cancel

Listar jobs / matar uno que sigue corriendo.

diff

Qué cambió en el worktree (stat_only:true = solo resumen).

bring_changes

Aplica el diff a tu repo real con git apply. No comitea.

help

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/git van siempre como array a spawn(), 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_changes usa git apply, nunca merge/rebase. Si el patch no aplica limpio, no toca nada.

  • cursor-agent tiene worktrees nativos (-w/--worktree-base); este MCP usa los suyos propios para controlar el base, la ruta y el symlink de node_modules.

  • job_cancel solo 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 metadata

Available Tools

16 tools
bring_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

    A3.9/5.0

    Scored across 16 tools

    Disambiguation5/5

    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 Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers