Terminal MCP Server

Ejecuta comandos en hosts locales o remotos a través de SSH. Soporta persistencia de sesión y variables de entorno.

Documentación

Terminal MCP Server

Aviso

El proyecto actual ya no se mantiene. Recomiendo que usen una herramienta de comandos más avanzada: Desktop Commander
El proyecto actual ya no se mantiene. Recomiendo a todos usar una herramienta MCP de terminal más avanzada: Desktop Commander

Documentación en chino

Terminal MCP Server es un servidor de Model Context Protocol (MCP) que permite ejecutar comandos en hosts locales o remotos. Proporciona una interfaz simple pero potente para que los modelos de IA y otras aplicaciones ejecuten comandos del sistema, ya sea en la máquina local o en hosts remotos a través de SSH.

Características

Ejecución de comandos local: Ejecuta comandos directamente en la máquina local.
Ejecución de comandos remota: Ejecuta comandos en hosts remotos a través de SSH.
Persistencia de sesión: Soporte para sesiones persistentes que reutilizan el mismo entorno de terminal durante un tiempo especificado (por defecto 20 minutos).
Variables de entorno: Establece variables de entorno personalizadas para los comandos.
Múltiples métodos de conexión: Conéctate a través de stdio o SSE (Server-Sent Events).

Instalación

Instalación mediante Smithery

Para instalar terminal-mcp-server para Claude Desktop automáticamente a través de Smithery:

npx -y @smithery/cli install @weidwonder/terminal-mcp-server --client claude

Instalación manual

# Clone the repository
git clone https://github.com/weidwonder/terminal-mcp-server.git
cd terminal-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Uso

Iniciar el servidor

# Start the server using stdio (default mode)
npm start

# Or run the built file directly
node build/index.js

Iniciar el servidor en modo SSE

El modo SSE (Server-Sent Events) te permite conectarte al servidor de forma remota a través de HTTP.

# Start the server in SSE mode
npm run start:sse

# Or run the built file directly with SSE flag
node build/index.js --sse

Puedes personalizar el servidor SSE con las siguientes opciones de línea de comandos:

Opción	Descripción	Por defecto
`--port` o `-p`	El puerto en el que escuchar	8080
`--endpoint` o `-e`	La ruta del endpoint	/sse
`--host` o `-h`	El host al que vincular	localhost

Ejemplo con opciones personalizadas:

# Start SSE server on port 3000, endpoint /mcp, and bind to all interfaces
node build/index.js --sse --port 3000 --endpoint /mcp --host 0.0.0.0

Esto iniciará el servidor y escuchará conexiones SSE en http://0.0.0.0:3000/mcp.

Pruebas con MCP Inspector

# Start the MCP Inspector tool
npm run inspector

La herramienta execute_command

La herramienta execute_command es la funcionalidad principal proporcionada por Terminal MCP Server, utilizada para ejecutar comandos en hosts locales o remotos.

Parámetros

Parámetro	Tipo	Requerido	Descripción
command	string	Sí	El comando a ejecutar
host	string	No	El host remoto al que conectarse. Si no se proporciona, el comando se ejecutará localmente
username	string	Requerido cuando se especifica el host	El nombre de usuario para la conexión SSH
session	string	No	Nombre de sesión, por defecto "default". El mismo nombre de sesión reutilizará el mismo entorno de terminal durante 20 minutos
env	object	No	Variables de entorno, por defecto un objeto vacío

Ejemplos

Ejecutar un comando localmente

{
  "command": "ls -la",
  "session": "my-local-session",
  "env": {
    "NODE_ENV": "development"
  }
}

Ejecutar un comando en un host remoto

{
  "host": "example.com",
  "username": "user",
  "command": "ls -la",
  "session": "my-remote-session",
  "env": {
    "NODE_ENV": "production"
  }
}

Configuración con asistentes de IA

Configuración con Roo Code

Abre VSCode e instala la extensión Roo Code
Abre el archivo de configuración de Roo Code: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
Añade la siguiente configuración:

Para modo stdio (conexión local)

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

Para modo SSE (conexión remota)

{
  "mcpServers": {
    "terminal-mcp-sse": {
      "url": "http://localhost:8080/sse",
      "headers": {}
    }
  }
}

Reemplaza localhost:8080/sse con la dirección, el puerto y el endpoint reales de tu servidor si los has personalizado.

Configuración con Cline

Abre el archivo de configuración de Cline: ~/.cline/config.json
Añade la siguiente configuración:

Para modo stdio (conexión local)

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

Para modo SSE (conexión remota)

{
  "mcpServers": {
    "terminal-mcp-sse": {
      "url": "http://localhost:8080/sse",
      "headers": {}
    }
  }
}

Configuración con Claude Desktop

Abre el archivo de configuración de Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
Añade la siguiente configuración:

Para modo stdio (conexión local)

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

Para modo SSE (conexión remota)

{
  "mcpServers": {
    "terminal-mcp-sse": {
      "url": "http://localhost:8080/sse",
      "headers": {}
    }
  }
}

Mejores prácticas

Ejecución de comandos

Antes de ejecutar comandos, es mejor determinar el tipo de sistema (Mac, Linux, etc.)
Usa rutas completas para evitar problemas relacionados con las rutas
Para secuencias de comandos que necesitan mantener el entorno, usa && para conectar múltiples comandos
Para comandos de larga duración, considera usar nohup o screen/tmux

Conexión SSH

Asegúrate de que la autenticación basada en claves SSH esté configurada
Si la conexión falla, verifica si el archivo de clave existe (ruta por defecto: ~/.ssh/id_rsa)
Asegúrate de que el servicio SSH esté ejecutándose en el host remoto

Gestión de sesiones

Usa el parámetro de sesión para mantener el entorno entre comandos relacionados
Para operaciones que requieren entornos específicos, usa el mismo nombre de sesión
Ten en cuenta que las sesiones se cerrarán automáticamente después de 20 minutos de inactividad

Manejo de errores

Los resultados de la ejecución de comandos incluyen tanto stdout como stderr
Revisa stderr para determinar si el comando se ejecutó correctamente
Para operaciones complejas, añade pasos de verificación para asegurar el éxito

Notas importantes

Para la ejecución remota de comandos, la autenticación basada en claves SSH debe configurarse de antemano
Para la ejecución local de comandos, los comandos se ejecutarán en el contexto del usuario que inició el servidor
El tiempo de espera de la sesión es de 20 minutos, después del cual la conexión se cerrará automáticamente