MCP de Shell Interactivo

Servidor MCP para sesiones de shell interactivas con soporte TUI. Proporciona a los agentes de IA terminales persistentes, navegación interactiva por prompts, lectura de pantalla renderizada y búsqueda de resultados.

Demo

Por qué existe esto

La mayoría de las herramientas de codificación por IA ejecutan comandos de shell de forma aislada: cada comando inicia una shell nueva, los prompts interactivos son imposibles y las aplicaciones TUI simplemente vuelcan códigos de escape sin procesar. Este servidor MCP proporciona sesiones PTY persistentes con un emulador de terminal virtual (@xterm/headless) para que los agentes puedan mantener el estado de la shell, navegar por prompts interactivos con las teclas de flecha y leer pantallas de terminal renderizadas como texto limpio.

Tres modos de salida:

Inicio rápido

git clone https://github.com/lightos/interactive-shell-mcp.git
cd interactive-shell-mcp
npm install && npm run build
claude mcp add interactive-shell node dist/src/server.js

Luego pregúntale a Claude: "monitoriza htop y dime qué está consumiendo más CPU"

Características

• Lectura de pantalla renderizada desde aplicaciones TUI mediante @xterm/headless

• waitForIdle en todas las herramientas de lectura (no más adivinanzas con sleep)

• Búsqueda en pantalla con coincidencia de texto y patrones regex

• Extracción de regiones rectangulares con coordenadas de fila/columna

• Lista blanca de shells: bash, zsh, fish, sh, dash, ksh, powershell.exe, pwsh, cmd.exe

• Limpieza automática tras 10 minutos de inactividad, detección de código de salida durante 60 segundos tras el cierre del proceso

• Multiplataforma: Unix/Linux/macOS + Windows

Casos de uso

• Andamiaje y migraciones interactivas: npx create-next-app, drizzle-kit push, prisma migrate, npm init, o cualquier CLI basada en inquirer/clack

• Monitorización del sistema: htop, btop, top, iftop, duf con búsqueda de procesos y extracción de regiones

• TUI de DevOps: lazydocker, lazygit, k9s, terraform console

• Sesiones remotas: ssh a servidores, incluyendo aplicaciones TUI anidadas sobre SSH

• CLI de bases de datos: psql, mysql, redis-cli, mongosh en modo interactivo

• Herramientas de red: netcat/ncat, nmap, airodump-ng, tcpdump

• REPLs y depuradores: python, node, irb, gdb/lldb

• Editores de texto: vim, nano, emacs -nw

Configuración de MCP

Claude Code (CLI)

claude mcp add interactive-shell node /path/to/interactive-shell-mcp/dist/src/server.js

Claude Desktop

Añadir a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "interactive-shell": {
      "command": "node",
      "args": ["/path/to/interactive-shell-mcp/dist/src/server.js"]
    }
  }
}

VS Code / Cursor

Añadir a tus ajustes de MCP (.vscode/mcp.json o ~/.cursor/mcp.json):

{
  "mcpServers": {
    "interactive-shell": {
      "command": "node",
      "args": ["/path/to/interactive-shell-mcp/dist/src/server.js"]
    }
  }
}

Referencia de herramientas

start_shell_session

Genera una nueva shell PTY con un emulador de terminal virtual.

Devuelve { sessionId, cols, rows }

send_shell_input

Escribe entrada en la PTY. Añade un retorno de carro por defecto.

read_shell_output

Lee la salida de la PTY. Tres modos: streaming (predeterminado), snapshot, screen.

El modo screen devuelve la posición del cursor, dimensiones del terminal y estado del búfer alternativo en los metadatos.

get_screen_region

Extrae texto de una región rectangular de la pantalla.

get_screen_cursor

Obtiene la posición del cursor y el texto de la línea actual.

Devuelve { cursor: { x, y }, currentLine, isAlternateBuffer }

search_screen

Busca texto o regex en la pantalla del terminal. Devuelve hasta 50 coincidencias.

Devuelve { results: [{ row, col, text }], count }

list_sessions

Lista todas las sesiones activas con metadatos. Sin parámetros.

Devuelve { sessions: [{ sessionId, shell, cols, rows, isAlternateBuffer, idleSeconds }] }

resize_shell

Cambia el tamaño del terminal de una sesión activa.

end_shell_session

Cierra la PTY y libera recursos.

Ejemplos de uso

Estos muestran los patrones de llamada a herramientas MCP para desarrolladores que crean integraciones. Los usuarios finales simplemente hablan con su agente de IA de forma natural.

Lectura de una aplicación TUI

await send_shell_input(sessionId, "htop");
const { output, metadata } = await read_shell_output(sessionId, {
  mode: "screen",
  waitForIdle: 500
});
// output: rendered htop as clean text (CPU bars, process table, etc.)
// metadata.isAlternateBuffer: true (htop uses alternate screen)

// Extract just the process list (rows 6-30)
const processes = await get_screen_region(sessionId, {
  startRow: 6, startCol: 0, endRow: 30, endCol: 120,
  trimWhitespace: true
});

Navegación por prompts interactivos

// Send arrow keys and enter in raw mode
await send_shell_input(sessionId, "\\x1b[B", { raw: true });  // down arrow
await send_shell_input(sessionId, " ", { raw: true });         // space to select
await send_shell_input(sessionId, "\\r", { raw: true });       // enter to confirm

// Read what the prompt looks like now
const screen = await read_shell_output(sessionId, {
  mode: "screen", waitForIdle: 300
});

Esperar a la salida de un comando

await send_shell_input(sessionId, "npm install");
const output = await read_shell_output(sessionId, {
  waitForIdle: 1000  // wait for 1s of silence
});

Búsqueda de contenido

// Find all error lines
const errors = await search_screen(sessionId, {
  pattern: "error|Error|ERROR",
  regex: true,
  waitForIdle: 500
});
// [{ row: 12, col: 0, text: "Error" }, ...]

Comportamiento de la sesión

• Limpieza automática: Las sesiones inactivas >10 minutos se eliminan automáticamente

• Detección de salida: Cuando una shell termina, las herramientas devuelven "Session exited with code N" durante 60 segundos en lugar de un error genérico de ID no válido

• Lista blanca de shells: Solo se pueden generar shells conocidas (bash, zsh, fish, sh, dash, ksh, powershell.exe, pwsh, cmd.exe). Los valores desconocidos vuelven al valor predeterminado de la plataforma.

Licencia

MIT