TermSSH MCP

✨ Por qué TermSSH MCP

La mayoría de las herramientas SSH para flujos de trabajo de IA se basan en ejecutar comando → obtener salida → listo.

Eso falla cuando la tarea real es interactiva:

• los instaladores hacen preguntas

• los shells mantienen el estado

• la depuración requiere múltiples pasos

• los despliegues necesitan cargas de archivos además de control de terminal

• los agentes necesitan observar, reaccionar y continuar

TermSSH MCP está construido para cubrir esa brecha.

En lugar de pretender que todo es un solo comando, ofrece a los clientes MCP un flujo de trabajo real al estilo operador:

abrir un shell → escribir entrada → leer salida → mantener contexto → subir archivos → continuar trabajando

🧠 Qué lo hace diferente

Centrado en terminal

Las sesiones de terminal interactivas son el modelo central, no una ocurrencia tardía.

Listo para agentes

Diseñado para clientes MCP, agentes de codificación y bucles de automatización.

Flujos de trabajo con estado

Reutiliza sesiones activas para que las tareas de varios pasos se sientan naturales y confiables.

Carga incluida

Mueve scripts, configuraciones, cargas útiles y artefactos generados a través de SFTP.

Multiplataforma

Funciona contra objetivos SSH de Linux y Windows.

Superficie de herramientas limpia

Herramientas MCP enfocadas para el control de terminal y la entrega remota de archivos.

🚀 Capacidades principales

• Sesiones de terminal SSH interactivas

• Flujo incremental de lectura/escritura de terminal

• Reutilización de sesiones de terminal gestionadas por defecto

• Creación opcional de sesiones múltiples forzadas

• Carga de archivos locales a través de SFTP

• Carga directa de texto y contenido en base64

• Soporte para redimensionamiento de terminal

• Soporte para objetivos SSH de Linux y Windows

• Interfaz nativa MCP para herramientas de IA

🧰 Conjunto de herramientas

upload-file

Sube un archivo local desde la máquina host MCP al servidor SSH remoto usando SFTP.

Parámetros

• localPath — ruta del archivo fuente local

• remotePath — ruta de destino en el host remoto

• createDirectories — crear directorios padres faltantes si es necesario

• overwrite — reemplazar un archivo remoto existente si está presente

• mode — modo POSIX opcional como 0644

upload-content

Sube texto directo o contenido en base64 al servidor remoto.

Parámetros

• content — texto sin formato o carga útil en base64

• encoding — utf8 o base64

• remotePath — ruta de destino en el host remoto

• createDirectories — crear directorios padres faltantes si es necesario

• overwrite — reemplazar un archivo remoto existente si está presente

• mode — modo POSIX opcional como 0644

terminal-start

Inicia una sesión de terminal remota interactiva.

Parámetros

• cwd — directorio de trabajo opcional después del inicio del shell

• shell — binario de shell opcional

• platformHint — auto, linux o windows

• elevated — intentar elevación su cuando esté configurado

• cols — ancho de la terminal

• rows — altura de la terminal

• env — variables de entorno opcionales

• multiSession — establecer en true para forzar una nueva sesión gestionada en lugar de reutilizar una existente

terminal-write

Escribe entrada en una sesión de terminal activa.

Parámetros

• sessionId — id de la sesión objetivo

• input — texto a enviar

• appendNewline — añadir una nueva línea automáticamente si es necesario

terminal-read

Lee la salida almacenada en búfer de una sesión de terminal.

Parámetros

• sessionId — id de la sesión objetivo

• sinceSequence — solo devolver salida más nueva que un número de secuencia dado

• maxChars — limitar el tamaño de la salida devuelta

• waitForMs — retraso de sondeo corto opcional

terminal-resize

Redimensiona una sesión de terminal activa.

Parámetros

• sessionId — id de la sesión objetivo

• cols — nuevo ancho

• rows — nueva altura

terminal-close

Cierra una sesión de terminal localmente.

Parámetros

• sessionId — id de la sesión objetivo

🔄 Flujo de trabajo típico

flowchart LR
    A[terminal-start] --> B[terminal-write]
    B --> C[terminal-read]
    C --> D{Need file?}
    D -- Yes --> E[upload-file / upload-content]
    D -- No --> F{Continue session?}
    E --> F
    F -- Yes --> B
    F -- No --> G[terminal-close]

Esto funciona especialmente bien para:

• instalaciones interactivas de paquetes

• configuración y aprovisionamiento remoto

• despliegues con carga de artefactos

• servicios de depuración en múltiples pasos

• flujos de trabajo de shell con estado donde el contexto importa

🛠 Instalación

Clonar el repositorio

git clone https://github.com/rayss868/termssh-mcp.git
cd termssh-mcp
npm install
npm run build

Instalar globalmente

npm install -g termssh-mcp

⚙ Configuración

Parámetros CLI requeridos

• host — nombre de host o dirección IP de la máquina remota

• user — nombre de usuario SSH

Parámetros CLI opcionales

• port — puerto SSH, por defecto 22

• password — contraseña SSH

• key — ruta a una clave SSH privada

• sudoPassword — contraseña opcional para flujos de trabajo orientados a sudo

• suPassword — contraseña opcional para elevación basada en su

• timeout — tiempo de espera de preparación SSH en milisegundos, por defecto 60000

• maxChars — límite de validación de longitud de comando, por defecto 1000; use none o 0 para modo ilimitado

🧩 Ejemplo de configuración MCP

{
  "mcpServers": {
    "termssh-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "termssh-mcp",
        "--",
        "--host=1.2.3.4",
        "--port=22",
        "--user=root",
        "--password=pass",
        "--timeout=30000",
        "--maxChars=none"
      ]
    }
  }
}

Ejemplo de clave SSH

{
  "mcpServers": {
    "termssh-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "termssh-mcp",
        "--",
        "--host=example.com",
        "--user=root",
        "--key=/path/to/private/key"
      ]
    }
  }
}

🤖 Ejemplo de Claude Code

Registra el servidor en Claude Code:

claude mcp add --transport stdio termssh-mcp -- npx -y termssh-mcp -- --host=YOUR_HOST --user=YOUR_USER --password=YOUR_PASSWORD

Con autenticación de clave SSH:

claude mcp add --transport stdio termssh-mcp -- npx -y termssh-mcp -- --host=example.com --user=root --key=/path/to/private/key

Con tiempo de espera extendido:

claude mcp add --transport stdio termssh-mcp -- npx -y termssh-mcp -- --host=192.168.1.100 --user=admin --password=your_password --timeout=120000 --maxChars=none

🎯 Ideal para

Desarrolladores

• acceso remoto a shell desde herramientas de codificación de IA

• sesiones de depuración con estado

• entrega de scripts y configuraciones

Equipos de DevOps / infraestructura

• inspección de servicios

• soporte de despliegue

• operaciones remotas de varios pasos

Creadores de agentes

• flujos de trabajo MCP nativos de terminal

• sesiones reutilizables

• bucles de automatización remota controlados

🏗 Desarrollo

Construir el proyecto:

npm run build

Ejecutar pruebas:

npm test

Usar el Inspector MCP:

npm run inspect

📁 Estructura del proyecto

• src/index.ts — punto de entrada del servidor MCP y registro de herramientas

• src/ssh-connection-manager.ts — manejo de la conexión SSH y ciclo de vida de la terminal

• src/upload.ts — ayudantes de carga y ayudantes de metadatos de sesión interactiva

• src/core.ts — validación compartida y primitivas de utilidad SSH

• test/upload-and-terminal.test.ts — cobertura de pruebas unitarias de carga/sesión

• test/maxChars.test.ts — cobertura de validación de comandos

• test/smoke.ssh.test.ts — pruebas de humo para el comportamiento exportado actual

🗺 Ideas para la hoja de ruta

• inspección más rica de metadatos de sesión

• mejor observabilidad de sesiones remotas

• características opcionales de persistencia de sesión

• más ejemplos para Claude Code y herramientas MCP

• plantillas de flujo de trabajo orientadas al despliegue

🔐 Nota de seguridad

TermSSH MCP proporciona acceso remoto a sistemas a través de SSH. Úselo solo en infraestructura que posea o que esté explícitamente autorizado a gestionar.

📜 Licencia

Publicado bajo la Licencia MIT.

🤝 Contribuyendo

Las contribuciones son bienvenidas. Consulte CONTRIBUTING.md para obtener orientación sobre contribuciones y CODE_OF_CONDUCT.md para el comportamiento esperado.