cmux-mcp

cmux-mcp

한국어

Servidor MCP que da a los agentes de IA control total sobre tu terminal cmux.

Permite que Claude ejecute comandos, lea la salida, gestione pestañas/paneles/espacios de trabajo/ventanas y envíe caracteres de control en tu terminal cmux, todo a través del Model Context Protocol. Funciona en segundo plano. Sin robo de foco.

Inicio rápido

Opción A: Plugin de Claude Code (Recomendado)

/plugin marketplace add daegweon/cmux-mcp
/plugin install cmux-mcp@cmux-tools

Eso es todo. El servidor MCP se configura automáticamente.

Opción B: npx (Sin necesidad de compilar)

Edita ~/.claude/settings.json:

{
  "mcpServers": {
    "cmux-mcp": {
      "command": "npx",
      "args": ["-y", "cmux-mcp"]
    }
  }
}

Reinicia Claude Code.

Opción C: Clonar y compilar

git clone https://github.com/daegweon/cmux-mcp.git
cd cmux-mcp
npm install && npm run build

Edita ~/.claude/settings.json:

{
  "mcpServers": {
    "cmux-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/cmux-mcp/build/index.js"]
    }
  }
}

Reinicia Claude Code.

{
  "mcpServers": {
    "cmux-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/cmux-mcp/build/index.js"]
    }
  }
}

Requisitos

• macOS
• cmux.app instalado y en ejecución
• Node.js 18+
• Modo de control de socket de cmux configurado en Automation o Open Access (Settings > Automation > Socket Control Mode)

Herramientas

cmux-mcp expone la CLI completa de cmux como herramientas MCP. Todas las herramientas de E/S de terminal admiten un parámetro opcional surface para apuntar a pestañas específicas.

E/S de terminal

Gestión de superficies (pestañas)

Gestión de paneles

Gestión de ventanas

Gestión de espacios de trabajo

Búsqueda y estructura

Notificaciones

Metadatos de la barra lateral

Registro

Búfer

Control de terminal

Hooks y varios

Navegador

Ejemplos del mundo real

Ejecutar pruebas y analizar fallos:

"Ejecuta la suite de pruebas y dime qué pruebas están fallando"

Claude envía npm test, lee la salida y resume los fallos.

Sesiones SSH con múltiples pestañas:

"Abre dos pestañas nuevas, haz SSH a server-a en una y a server-b en la otra, luego compara su uso de disco"

Claude crea pestañas, envía comandos SSH a cada una, lee la salida de ambas y compara.

Sesión REPL interactiva:

"Abre un REPL de Python y comprueba si pandas está instalado"

Claude inicia python3, escribe import pandas, lee el resultado e informa.

Gestión de procesos de larga duración:

"Inicia el servidor de desarrollo, espera a que esté listo y luego ejecuta la comprobación de salud"

Claude envía el comando de inicio, consulta la salida hasta que aparece "ready" y luego ejecuta el siguiente comando.

¿Por qué cmux-mcp?

Operación en segundo plano

cmux-mcp utiliza la CLI nativa de cmux (cmux send, cmux read-screen, cmux send-key) que se comunica a través de un socket Unix. Esto significa:

• Funciona mientras cmux está en segundo plano
• Sin robo de foco de ventana
• Sin retrasos de activación de AppleScript
• Fiable incluso durante la inicialización de la aplicación

CLI vs AppleScript

Este proyecto se bifurcó de ferrislucas/iterm-mcp y se reescribió por completo. He aquí por qué:

Detección inteligente de finalización

cmux-mcp no espera a ciegas después de enviar un comando. Supervisa la actividad de CPU del TTY para saber cuándo termina realmente un comando, incluso para comandos que producen salida con el tiempo. A partir de v1.3.1, el intervalo de sondeo se redujo de 350ms a 150ms y el umbral de inactividad de 1000ms a 500ms, lo que hace que write_to_terminal sea aproximadamente 2 veces más rápido.

Eficiente en tokens

Los agentes leen solo las líneas que necesitan. ¿Un npm test que produce 500 líneas de salida? El agente primero recibe el mensaje "se generaron 500 líneas" y luego lee solo las últimas 20 líneas para comprobar si hay errores. Sin desperdicio de ventana de contexto.

Manejo de problemas conocidos de cmux

La arquitectura de cmux-mcp evita varios casos límite conocidos de cmux:

Arquitectura

MCP Client (Claude Code, Claude Desktop, etc.)
    |  stdio
cmux-mcp server
    |  child_process
cmux CLI (send / read-screen / send-key / ...)
    |  Unix socket
cmux.app (Ghostty-based terminal)
    |
macOS PTY

Módulos principales:

Desarrollo

npm run build          # Compile TypeScript
npm run watch          # Auto-rebuild on changes
npm test               # Run unit tests
npm run e2e            # Run E2E tests (requires running cmux)
npm run inspector      # Open MCP Inspector for interactive debugging

Seguridad

• Sin restricciones de comandos integradas. Los comandos se ejecutan con los permisos de tu shell.
• Supervisa la actividad de la IA e interrumpe si es necesario.
• Comienza con tareas enfocadas hasta que te familiarices con el comportamiento del modelo.

Créditos

• Bifurcado de ferrislucas/iterm-mcp
• Construido para cmux por manaflow.ai

Privacidad

cmux-mcp no recopila ni transmite ningún dato. Todo el procesamiento es local. Consulta PRIVACY.md para más detalles.

Licencia

MIT