pty-mcp

Un servidor MCP (Model Context Protocol) que proporciona a los agentes de IA sesiones de terminal interactivas: shells locales, SSH, puertos serie y sesiones remotas persistentes que sobreviven a las desconexiones.

Creado para administradores de sistemas e ingenieros de redes que desean que la IA ayude con la gestión real de servidores y dispositivos, no solo con la generación de código.

Por qué

Los agentes de IA ejecutan comandos en shells no interactivos. No pueden:

• Conectarse por SSH a un servidor e interactuar con procesos en ejecución

• Conectarse a routers o switches a través de consola serie

• Monitorear registros y reaccionar cuando ocurre un evento específico

• Mantener el estado de la sesión a través de múltiples comandos

• Esperar a que un servidor se reinicie y detectar cuándo vuelve a estar activo

pty-mcp resuelve todo esto proporcionando sesiones PTY reales a través de MCP.

Sin pty-mcp, los agentes de IA recurren a bucles sleep 30 && check_status, consumiendo ciclos de CPU y llamadas a la API esperando a que sucedan las cosas. Con wait_for, el agente se bloquea en el lado del servidor hasta que ocurre el evento. Menos sondeo, menos energía, mejor para los osos polares. 🐻❄️

Casos de uso

Administración de servidores

# Reboot a server and wait until it's back online
create_local_session("ping myserver")
read_output(wait_for: "bytes from", timeout: 300)
→ blocks until server responds after reboot (~80s, one tool call)

Gestión de dispositivos de red

# Connect to a router via serial console
create_serial_session(port: "/dev/ttyUSB0", baud: 9600)
send_input("show interfaces status")
read_output(wait_for: "\\$")

Monitoreo de registros y alertas

# Watch logs and act when something happens
create_ssh_session(host: "prod", user: "admin")
send_input("tail -f /var/log/app.log")
read_output(wait_for: "ERROR|CRITICAL", timeout: 3600)
→ returns the error line + context when it appears

Tareas de larga duración que sobreviven a las desconexiones

create_ssh_session(host: "server", user: "admin", persistent: true)
send_input("apt upgrade -y")
detach_session()          → close Claude Code, task continues
# Reconnect later to check result

Características

Arquitectura

┌─────────────────────────────────────────────────────┐
│ AI Agent (Claude Code, etc.)                        │
│                                                     │
│  MCP Tools: create_local_session, send_input,       │
│             send_control, read_output, close_session │
└──────────────────────┬──────────────────────────────┘
                       │ JSON-RPC stdio
┌──────────────────────┴──────────────────────────────┐
│ pty-mcp (MCP Server)                                │
│                                                     │
│  Session Manager                                    │
│  ├── LocalSession  (local PTY via creack/pty)       │
│  ├── SSHSession    (remote PTY via x/crypto/ssh)    │
│  ├── SerialSession (serial port via go.bug.st)      │
│  └── RemoteSession (persistent via ai-tmux)         │
└─────────────────────────────────────────────────────┘

Persistent mode (ai-tmux):

  pty-mcp ──SSH──▶ ai-tmux client ──Unix socket──▶ ai-tmux server (daemon)
                                                     ├── PTY: bash
                                                     ├── PTY: ssh admin@router
                                                     └── PTY: tail -f /var/log/syslog

Inicio rápido

Plugin de Claude Code (recomendado)

Instala el binario automáticamente y registra el servidor MCP:

claude plugin marketplace add raychao-oao/pty-mcp
claude plugin install pty-mcp@pty-mcp

Reinicie Claude Code: el binario se descarga automáticamente al iniciar la sesión, luego reinicie una vez más para activarlo. No se necesita claude mcp add manual.

Actualización:

claude plugin marketplace update pty-mcp
claude plugin update pty-mcp@pty-mcp

Reinicie Claude Code: el nuevo binario se descarga automáticamente al iniciar la sesión, luego reinicie una vez más para aplicar la actualización.

Instalación manual

Instalación + registro en una línea (macOS / Linux / WSL2):

curl -fsSL https://raw.githubusercontent.com/raychao-oao/pty-mcp/main/install.sh | sh
claude mcp add pty-mcp -- /usr/local/bin/pty-mcp

Reinicie Claude Code y las herramientas estarán disponibles.

Descargar desde GitHub Releases:

Vaya a Releases, descargue el binario para su plataforma y hágalo ejecutable:

chmod +x pty-mcp-*
sudo mv pty-mcp-* /usr/local/bin/pty-mcp
claude mcp add pty-mcp -- /usr/local/bin/pty-mcp

Compilar desde el código fuente (requiere Go 1.25+):

go install github.com/raychao-oao/pty-mcp@latest
claude mcp add pty-mcp -- $(go env GOPATH)/bin/pty-mcp

Notas sobre WSL2

pty-mcp funciona en WSL2 sin configuración adicional. Utilice el binario de Linux:

# Inside WSL2
curl -fsSL https://raw.githubusercontent.com/raychao-oao/pty-mcp/main/install.sh | sh
claude mcp add pty-mcp -- /usr/local/bin/pty-mcp

Opcional: Instalar ai-tmux en servidores remotos

Para sesiones persistentes que sobreviven a las desconexiones SSH, instale ai-tmux en su servidor remoto:

# Download for your server's architecture
curl -fsSL https://raw.githubusercontent.com/raychao-oao/pty-mcp/main/install.sh | sh
# Or just copy the binary:
scp /usr/local/bin/ai-tmux your-server:/usr/local/bin/ai-tmux

Ejemplos de uso

Una vez registrado, el agente de IA puede usar estas herramientas MCP:

Shell interactivo local:

create_local_session()                    → {session_id, type: "local"}
send_input(session_id, "cd /tmp && ls")   → {output: "...", is_complete: true}
send_input(session_id, "python3")         → start Python REPL
send_input(session_id, "print('hello')")  → {output: "hello\n>>>"}
send_control(session_id, "ctrl+d")        → exit Python
close_session(session_id)

SSH a servidor remoto:

create_ssh_session(host: "myserver", user: "admin")
send_input(session_id, "top")
send_control(session_id, "ctrl+c")        → stop top

Esperar por patrón (v0.2.0):

create_local_session("ping myserver")
read_output(session_id, wait_for: "bytes from", timeout: 300)
→ blocks until server responds or 5 min timeout

send_input(session_id, "docker-compose up")
read_output(session_id, wait_for: "ready|error", timeout: 60, context_lines: 3)
→ returns matched line + 3 lines of context

Enviar secreto / contraseña (v0.3.0):

# AI detects a password prompt, calls send_secret instead of handling the password itself
create_ssh_session(host: "router", user: "admin")
read_output(session_id, wait_for: "Password:")   → session is waiting for input

send_secret(session_id, prompt: "Router admin password:")
→ native GUI dialog appears on the operator's screen (macOS: system dialog,
   WSL2: Windows Get-Credential, Linux: zenity/kdialog)
→ operator types password — it is sent directly to the PTY session
→ AI only sees: {success: true, length: 12}
→ password never appears in AI context or logs

Sesión persistente (sobrevive a la desconexión SSH):

create_ssh_session(host: "server", user: "admin", persistent: true)
send_input(session_id, "make build")      → start long build
detach_session(session_id)                → disconnect, build continues

# Later (even after restart):
list_remote_sessions(host: "server", user: "admin")  → see running sessions
create_ssh_session(host: "server", user: "admin", session_id: "abc123")  → reattach
send_input(session_id, "echo $?")         → check build result

Herramientas MCP

¹ Soporte de plataforma para send_secret: macOS utiliza un diálogo de contraseña nativo (osascript). WSL2 utiliza powershell.exe Get-Credential (diálogo GUI de Windows). Linux con un servidor de visualización utiliza zenity o kdialog. Linux sin interfaz gráfica recurre a /dev/tty.

Registro de auditoría

pty-mcp incluye una función de registro de auditoría opcional que registra cada comando send_input en un recolector central. Esto permite a los equipos revisar y rastrear lo que hicieron los agentes de IA durante una sesión.

Importante: Este es un registro de operaciones voluntario y de autoinforme. Depende de que los operadores elijan habilitarlo y ejecutar el recolector. Debido a que pty-mcp se ejecuta en la propia máquina del operador, no existe un mecanismo técnico para forzar el registro: un operador no conforme podría simplemente ejecutar pty-mcp sin la auditoría habilitada. Esta función proporciona trazabilidad para los equipos que la desean, pero no es un sustituto de las herramientas de auditoría a nivel de sistema (por ejemplo, auditd, reenvío de syslog, grabación de sesiones SSH) en entornos donde se requiere cumplimiento de auditoría.

Qué registra

• Marca de tiempo, identidad del operador, ID de sesión, tipo de sesión (local/ssh/serial), host de destino

• La entrada exacta enviada a través de send_input (incluidas las entradas raw=true como selecciones de menú)

• Fragmento de salida (primeros 2 KB) después de cada comando

• Un cmd_id que vincula el comando con su salida

send_secret nunca se registra: los secretos ingresados a través del diálogo GUI no aparecen en el registro de auditoría.

Configuración

Cada operador ejecuta una vez para crear su configuración y generar un token:

pty-mcp audit init

Esto crea ~/.config/pty-mcp/config (chmod 600) con un token generado aleatoriamente e imprime el token para compartir con el administrador del recolector.

El administrador del recolector inicia el servidor (usando el token de la salida de init):

PTY_MCP_AUDIT_TOKEN=<token-from-init> \
  pty-mcp audit serve --port 9099 --log /var/log/pty-mcp-audit.jsonl

Habilitar auditoría después de configurar la URL del recolector en la configuración:

# Edit config and set: audit-url=http://your-collector:9099
pty-mcp audit enable
# Restart Claude Code to apply

Para detener temporalmente el registro sin perder su configuración:

pty-mcp audit disable

Los operadores sin un archivo de configuración no se ven afectados: la auditoría está desactivada de forma predeterminada.

Modos de auditoría

Revisión de registros

Los registros se almacenan como JSONL (un objeto JSON por línea), legibles con herramientas estándar:

# All commands by operator ray
grep '"user":"ray"' /var/log/pty-mcp-audit.jsonl | jq .

# Commands sent to a specific host
jq 'select(.target == "root@prod01")' /var/log/pty-mcp-audit.jsonl

ai-tmux: Demonio de terminal persistente

ai-tmux es un demonio ligero que se ejecuta en servidores remotos, manteniendo las sesiones PTY vivas a través de las desconexiones SSH. Piense en él como un tmux diseñado para agentes de IA.

Instalar en servidor remoto

# Cross-compile for Linux
GOOS=linux GOARCH=amd64 go build -o ai-tmux-linux ./cmd/ai-tmux/

# Copy to server
scp ai-tmux-linux server:~/ai-tmux
ssh server "chmod +x ~/ai-tmux && sudo mv ~/ai-tmux /usr/local/bin/ai-tmux"

Cómo funciona

• ai-tmux server — modo demonio, escucha en socket Unix, gestiona sesiones PTY

• ai-tmux client — modo puente, reenvía el protocolo JSON sobre stdin/stdout (utilizado por pty-mcp sobre SSH)

• ai-tmux list — listar sesiones activas

El demonio se inicia automáticamente cuando pty-mcp se conecta con persistent: true. Las sesiones se eliminan después de 30 minutos de inactividad.

Soporte de configuración SSH

pty-mcp lee ~/.ssh/config para resolver alias de host:

# ~/.ssh/config
Host myserver
    HostName 192.168.1.100
    User admin
    Port 2222
    IdentityFile ~/.ssh/id_ed25519

create_ssh_session(host: "myserver", user: "admin")
# Automatically resolves hostname, port, and identity file

Requisitos

• Go 1.25+

• Para serie: permisos de dispositivo adecuados

• Para sesiones persistentes: binario ai-tmux en el servidor remoto

Registro de cambios

Consulte CHANGELOG.md para ver el historial de versiones.

Licencia

MIT