🔗 RemoteShell MCP

A Model Context Protocol (MCP) server that enables LLMs to securely manage and execute commands on remote SSH servers.

✨ Características

• 🔐 Gestión segura de credenciales - Guardar los perfiles de servidor SSH una vez, sin necesidad de volver a escribir las credenciales

• 💻 Ejecución remota de comandos - Ejecutar comandos de shell no interactivos de forma remota

• 📁 Operaciones de archivos - Subir/descargar archivos mediante SFTP

• 🤖 Impulsado por LLM - Construido con FastMCP y Paramiko

Related MCP server: SSH MCP Server

🚀 Instalación

RemoteShell es un servidor MCP stdio distribuido en PyPI. Ejecútalo directamente con uvx — no se requiere ningún paso de instalación. Luego registra el servidor con tu agente de codificación de IA:

Claude Code

claude mcp add remoteshell --scope user -- uvx remoteshell-mcp

Codex

codex mcp add remoteshell -- uvx remoteshell-mcp

Otros agentes — haz clic en el tuyo para expandir 👇

cursor mcp add remoteshell -- uvx remoteshell-mcp

Edita ~/.gemini/config/mcp_config.json (global) o .agents/mcp_config.json (proyecto):

{
  "mcpServers": {
    "remoteshell": {
      "command": "uvx",
      "args": ["remoteshell-mcp"]
    }
  }
}

O abre la vista MCP Servers en la TUI de Antigravity y ejecuta el comando /mcp.

opencode mcp add

Elige local y luego introduce uvx remoteshell-mcp.

Edita ~/.hermes/config.yaml:

mcp_servers:
  remoteshell:
    command: "uvx"
    args: ["remoteshell-mcp"]

Ejecuta /reload-mcp en la TUI de Hermes para que el nuevo servidor se cargue.

Edita ~/.openclaw/openclaw.json:

{
  "mcp": {
    "servers": {
      "remoteshell": {
        "command": "uvx",
        "args": ["remoteshell-mcp"]
      }
    }
  }
}

O ejecuta openclaw configure para añadirlo mediante el asistente interactivo.

Añade esto a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "remoteshell": {
      "command": "uvx",
      "args": ["remoteshell-mcp"]
    }
  }
}

📖 Uso

¡Empezar es fácil! Puedes:

1. 🤖 Deja que el LLM configure por ti - Simplemente indica al LLM tu host, nombre de usuario, contraseña, etc., y pídele que configure el servidor

2. ⚙️ Configuración manual - Edita directamente el archivo de configuración en ~/.config/remoteshell/hosts.json

💾 Configuración y almacenamiento

RemoteShell almacena de forma segura tus configuraciones de servidor en:

~/.config/remoteshell/hosts.json

🔧 Gestión de configuración

• Gestionado por LLM: El LLM gestiona automáticamente este archivo usando las herramientas save_server y remove_server

• Edición manual: También puedes editar directamente el archivo JSON para configuraciones avanzadas

📋 Ejemplo de configuración

{
  "version": 1,
  "servers": {
    "production-server": {
      "host": "1.2.3.4",
      "user": "root",
      "port": 22,
      "auth_type": "password",
      "password": "your_secure_password",
      "last_connected": null
    },
    "staging-server": {
      "host": "staging.example.com",
      "user": "ubuntu",
      "port": 22,
      "auth_type": "private_key",
      "private_key": "~/.ssh/id_rsa",
      "last_connected": "2025-01-01T00:00:00+00:00"
    }
  }
}

🔒 Nota de seguridad

En sistemas POSIX, protege tu archivo de configuración:

chmod 600 ~/.config/remoteshell/hosts.json

🛠️ Herramientas disponibles

RemoteShell proporciona las siguientes herramientas MCP para la gestión de servidores remotos:

📋 list_servers()

Propósito: Muestra todos los perfiles de servidor guardados con su estado de conexión y última actividad.

Cuándo usarla:

• El usuario pide "conectar al servidor" o "mostrar máquinas"

• No se proporciona un connection_id específico

• Se necesita ver los servidores disponibles

Ejemplo: "Muéstrame qué servidores tengo configurados" → Devuelve una lista de todos los servidores guardados con su estado en línea

💾 save_server(connection_id, host, user, auth_type, credential, port)

Propósito: Crea o actualiza un perfil de servidor con credenciales de autenticación.

Parámetros:

• connection_id: Identificador único del servidor (p. ej., "production", "staging")

• host: Nombre de host o dirección IP del servidor

• user: Nombre de usuario SSH

• auth_type: "password" o "private_key"

• credential:

  • Para password: Cadena de contraseña en texto plano

  • Para private_key: Ruta del archivo (p. ej., ~/.ssh/id_rsa) o contenido de la clave PEM

• port: Puerto SSH (opcional; por defecto es 22 y conserva el puerto guardado existente si se omite)

Cuándo usarla:

• Añadir una nueva configuración de servidor

• Actualizar credenciales tras un fallo de autenticación

• Cambiar los detalles de conexión del servidor

🗑️ remove_server(connection_id)

Propósito: Elimina permanentemente un perfil de servidor del almacenamiento.

Cuándo usarla:

• El usuario solicita explícitamente eliminar u olvidar un servidor

• El servidor ya no es accesible o necesario

⚠️ Advertencia: Esta acción no se puede deshacer

⚡ execute_command(connection_id, command)

Propósito: Ejecuta comandos de shell no interactivos de forma remota y devuelve los resultados.

Devuelve: stdout, stderr y exit_code

Cuándo usarla:

• Ejecutar comandos del sistema, scripts o utilidades

• Comprobar el estado del servidor, uso de disco, listas de procesos

• Operaciones de archivos, gestión de paquetes, etc.

Cuándo NO usarla:

• Programas interactivos (vim, htop, top)

• Comandos que requieren entrada manual (prompts [Y/n]) - a menos que se usen banderas como -y

Ejemplo: execute_command(connection_id="production", command="df -h")

📤 upload_file(connection_id, local_path, remote_path)

Propósito: Sube archivos desde tu máquina local a un servidor remoto mediante SFTP.

Parámetros:

• local_path: Ruta del archivo en tu máquina local

• remote_path: Ruta de destino en el servidor remoto

Notas:

• Si remote_path es un directorio, se conserva el nombre de archivo original

• Si se omite local_path, el servidor selecciona una ruta predeterminada y la devuelve en la respuesta

📥 download_file(connection_id, remote_path, local_path)

Propósito: Descarga archivos desde un servidor remoto a tu máquina local mediante SFTP.

Parámetros:

• remote_path: Ruta del archivo en el servidor remoto

• local_path: Ruta de destino en tu máquina local

Notas:

• Si se omite local_path, el valor predeterminado es: ~/.config/remoteshell/downloads/<connection_id>/<basename>

🧪 Desarrollo

Configuración de desarrollo local

Para el desarrollo local, usa esta configuración de MCP:

{
  "mcpServers": {
    "remoteshell": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/remoteShell-mcp", "run", "remoteshell-mcp"]
    }
  }
}

Ejecutar pruebas

uv run pytest