Tmux MCP Server

Proporciona ejecución persistente de shell a través de sesiones de tmux.

GitHub
1
Prueba este MCPPatrocinado

Documentación

Este es un software experimental destinado únicamente a fines de prueba y desarrollo. No lo utilice en entornos de producción ni con datos sensibles.

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona ejecución persistente de shell a través de sesiones de tmux. Este servidor permite a los asistentes de IA ejecutar comandos en un shell persistente. Esto desbloquea muchas posibilidades, como la orquestación de agentes... final_optimized

Características

  • Arquitectura de doble ventana: Cada espacio de trabajo tiene dos ventanas: exec para la ejecución de comandos y ui para la visualización limpia de la salida
  • Espacios de trabajo persistentes: Ejecute comandos en sesiones de tmux que persisten entre reinicios del cliente MCP
  • Soporte de procesos interactivos: Maneje procesos de larga duración, REPLs y comandos interactivos
  • Aislamiento de espacios de trabajo: Múltiples espacios de trabajo aislados para diferentes proyectos o tareas
  • Gestión limpia de interfaz: Ventanas separadas para la ejecución y la salida orientada al usuario
  • Gestión automática de sesiones: Cree, destruya y supervise espacios de trabajo sin problemas

Instalación

🚨 ADVERTENCIA DE SEGURIDAD: Este software permite a los asistentes de IA ejecutar comandos de shell arbitrarios en su sistema. Instálelo y úselo únicamente en entornos de prueba aislados. Nunca lo use en sistemas con datos sensibles ni en entornos de producción.

Requisitos previos

  • Node.js 18.0.0 o superior
  • tmux instalado en su sistema
    • Ubuntu/Debian: sudo apt install tmux
    • macOS: brew install tmux
    • CentOS/RHEL: sudo yum install tmux

Instalar desde npm

npm install -g tmux-mcp-server

Instalar desde el código fuente

git clone https://github.com/TNTisdial/persistent-shell-mcp.git
cd persistent-shell-mcp
npm install
npm link

Uso

Configuración del cliente MCP

Añada a la configuración de su cliente MCP:

{
  "mcpServers": {
    "tmux-shell": {
      "command": "tmux-mcp-server"
    }
  }
}

Herramientas disponibles

Herramientas principales de ejecución

execute_command

Ejecuta comandos que se completan rápidamente y devuelve la salida completa. Utiliza la ventana exec.

execute_command({
  command: "ls -la", 
  workspace_id: "my-project"
})

start_process

Inicia procesos de larga duración o interactivos. Puede dirigirse a cualquiera de las dos ventanas:

  • Ventana exec (predeterminada): Para procesos en segundo plano
  • Ventana ui: Para aplicaciones interactivas que necesitan visibilidad del usuario
start_process({
  command: "python3", 
  workspace_id: "dev",
  target_window: "ui"  // For interactive apps like vim, python REPL
})

get_output

Captura la salida actual del terminal desde cualquiera de las dos ventanas:

  • Ventana ui (predeterminada): Salida limpia orientada al usuario
  • Ventana exec: Shell sin procesar con todos los comandos
get_output({
  workspace_id: "dev",
  window_name: "ui"  // or "exec" for raw output
})

send_input

Envía entrada a los procesos en ejecución en cualquiera de las dos ventanas.

send_input({
  text: "print('Hello World')", 
  workspace_id: "dev",
  target_window: "ui"
})

stop_process

Detiene el proceso actualmente en ejecución en la ventana de ejecución (envía Ctrl+C).

stop_process({workspace_id: "dev"})

Herramientas de gestión de espacios de trabajo

create_workspace

Crea un nuevo espacio de trabajo aislado con doble ventana.

destroy_workspace

Destruye un espacio de trabajo y todos sus procesos.

list_workspaces

Lista todos los espacios de trabajo activos.

Arquitectura

Diseño de doble ventana

Cada espacio de trabajo consta de dos ventanas de tmux:

  1. Ventana exec: Shell sin procesar para la ejecución de comandos

    • Maneja toda la ejecución de comandos
    • Muestra el historial completo del shell y los avisos
    • Se utiliza para procesos en segundo plano

  2. Ventana ui: Visualización limpia de la salida

    • Muestra una salida limpia para la interacción del usuario
    • Se utiliza para aplicaciones interactivas
    • Proporciona una mejor experiencia de usuario

Aislamiento de espacios de trabajo

  • Cada espacio de trabajo es una sesión de tmux separada
  • Directorios de trabajo y entornos independientes
  • Los procesos no interfieren entre espacios de trabajo
  • Separación limpia de diferentes proyectos/tareas

Flujos de trabajo comunes

Ejecución rápida de comandos

// Execute and get results immediately
execute_command({command: "npm install", workspace_id: "frontend"})
execute_command({command: "git status", workspace_id: "frontend"})

Desarrollo interactivo

// Start Python REPL in UI window
start_process({
  command: "python3", 
  workspace_id: "python-dev",
  target_window: "ui"
})

// Send Python commands
send_input({text: "import os", workspace_id: "python-dev", target_window: "ui"})
send_input({text: "print(os.getcwd())", workspace_id: "python-dev", target_window: "ui"})

// Check output
get_output({workspace_id: "python-dev", window_name: "ui"})

Gestión de procesos en segundo plano

// Start server in background
start_process({command: "npm run dev", workspace_id: "server"})

// Check server status
get_output({workspace_id: "server", window_name: "exec"})

// Stop server when done
stop_process({workspace_id: "server"})

Desarrollo multiproyecto

// Frontend workspace
create_workspace({workspace_id: "frontend"})
execute_command({command: "cd /path/to/frontend", workspace_id: "frontend"})

// Backend workspace  
create_workspace({workspace_id: "backend"})
execute_command({command: "cd /path/to/backend", workspace_id: "backend"})

// Database workspace
create_workspace({workspace_id: "database"})
start_process({command: "mysql -u root -p", workspace_id: "database", target_window: "ui"})

Estructura del proyecto

tmux-mcp/
├── src/
│   ├── server.js          # Main MCP server and tool definitions
│   ├── tmux-manager.js    # Tmux session and window management
│   └── index.js           # Entry point
├── bin/
│   └── tmux-mcp-server    # Executable script
├── package.json
└── README.md

Solución de problemas

Tmux no encontrado

Error: tmux command not found

Instale tmux: sudo apt install tmux (Ubuntu/Debian) o brew install tmux (macOS)

Error al crear el espacio de trabajo

Error: Failed to create workspace

Compruebe si el servidor de tmux está en ejecución y si tiene permisos para crear sesiones

Comandos que no responden

Check workspace status with get_output

Utilice get_output con window_name: "exec" para ver el estado sin procesar del shell

Proceso bloqueado

Use stop_process to send Ctrl+C

Envíe la señal de interrupción con stop_process para terminar los procesos bloqueados

Licencia

MIT