Servidor MCP de Super Shell

Un servidor MCP (Protocolo de Contexto de Modelo) para ejecutar comandos de shell en múltiples plataformas (Windows, macOS, Linux). Este servidor proporciona una forma segura de ejecutar comandos de shell con mecanismos integrados de lista blanca y aprobación.

Características

• Ejecutar comandos de shell a través de MCP en Windows, macOS y Linux
• Detección automática de plataforma y selección de shell
• Soporte para múltiples shells:
  • Ventanas : cmd.exe, PowerShell
  • macOS : zsh, bash, sh
  • Linux : bash, sh, zsh
• Lista blanca de comandos con niveles de seguridad:
  • Seguro : Comandos que se pueden ejecutar sin aprobación
  • Requiere aprobación : comandos que necesitan aprobación explícita antes de su ejecución
  • Prohibido : Comandos que están bloqueados explícitamente
• Listas blancas de comandos específicos de la plataforma
• Flujo de trabajo de aprobación sin bloqueo para comandos potencialmente peligrosos
• Sistema de registro integral con registros basados en archivos
• Herramientas integrales de gestión de comandos
• Herramienta de información de plataforma para diagnóstico

Instalación

Instalación mediante herrería

Para instalar Super Shell MCP Server para Claude Desktop automáticamente a través de Smithery :

Instalación manual

Uso

Iniciando el servidor

O directamente:

Configuración en Roo Code y Claude Desktop

Tanto Roo Code como Claude Desktop utilizan un formato de configuración similar para los servidores MCP. A continuación, se explica cómo configurar el servidor MCP de Super Shell:

Opción 1: Usar NPX (recomendado)

La forma más sencilla de usar Super Shell MCP es con NPX, que instala y ejecuta automáticamente el paquete desde npm sin necesidad de configuración manual. El paquete está disponible en NPM en https://www.npmjs.com/package/super-shell-mcp .

Configuración del código Roo con NPX

Configuración de escritorio de Claude con NPX

Opción 2: Utilizar la instalación local

Si prefiere utilizar una instalación local, agregue lo siguiente a su archivo de configuración de Roo Code MCP (ubicado en ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json ):

Opcionalmente, puede especificar un shell personalizado agregando un parámetro de shell:

Ejemplo de Windows 11

Configuración del escritorio de Claude

Agregue lo siguiente a su archivo de configuración de Claude Desktop (ubicado en ~/Library/Application Support/Claude/claude_desktop_config.json ):

Para los usuarios de Windows, el archivo de configuración normalmente se encuentra en %APPDATA%\Claude\claude_desktop_config.json .

Configuración específica de la plataforma

Ventanas

• Shell predeterminado: cmd.exe (o PowerShell si está disponible)
• Rutas de configuración:
  • Código Roo: %APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json
  • Escritorio de Claude: %APPDATA%\Claude\claude_desktop_config.json
• Ejemplos de rutas de shell:
  • cmd.exe: C:\\Windows\\System32\\cmd.exe
  • PowerShell: C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe
  • Núcleo de PowerShell: C:\\Program Files\\PowerShell\\7\\pwsh.exe

macOS

• Shell predeterminado: /bin/zsh
• Rutas de configuración:
  • Código Roo: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
  • Escritorio de Claude: ~/Library/Application Support/Claude/claude_desktop_config.json
• Ejemplos de rutas de shell:
  • zsh: /bin/zsh
  • bash: /bin/bash
  • sh: /bin/sh

Linux

• Shell predeterminado: /bin/bash (o variable de entorno $SHELL)
• Rutas de configuración:
  • Código Roo: ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
  • Escritorio de Claude: ~/.config/Claude/claude_desktop_config.json
• Ejemplos de rutas de shell:
  • bash: /bin/bash
  • sh: /bin/sh
  • zsh: /usr/bin/zsh

Opcionalmente, puede especificar un shell personalizado:

Reemplace /path/to/super-shell-mcp con la ruta real donde clonó el repositorio.

Nota :

• Para Roo Code: Se recomienda configurar alwaysAllow con una matriz vacía [] por razones de seguridad, ya que solicitará aprobación antes de ejecutar cualquier comando. Si desea permitir comandos específicos sin solicitar aprobación, puede agregar sus nombres a la matriz, por ejemplo: "alwaysAllow": ["execute_command", "get_whitelist"] .
• Para Claude Desktop: Se recomienda configurar alwaysAllow como false por razones de seguridad. Claude Desktop utiliza un valor booleano en lugar de una matriz, donde false significa que todos los comandos requieren aprobación y true significa que todos los comandos se permiten sin solicitud.

Importante : El parámetro alwaysAllow lo procesa el cliente MCP (Roo Code o Claude Desktop), no el propio servidor MCP de Super Shell. El servidor funcionará correctamente con ambos formatos, ya que el cliente gestiona el proceso de aprobación antes de enviar las solicitudes al servidor.

Herramientas disponibles

El servidor expone las siguientes herramientas MCP:

get_platform_info

Obtenga información sobre la plataforma y shell actuales.

execute_command

Ejecutar un comando de shell en la plataforma actual.

get_whitelist

Obtenga la lista de comandos incluidos en la lista blanca.

add_to_whitelist

Añade un comando a la lista blanca.

update_security_level

Actualizar el nivel de seguridad de un comando incluido en la lista blanca.

remove_from_whitelist

Eliminar un comando de la lista blanca.

get_pending_commands

Obtenga la lista de comandos pendientes de aprobación.

approve_command

Aprobar un comando pendiente.

deny_command

Denegar un comando pendiente.

Comandos predeterminados incluidos en la lista blanca

El servidor incluye listas blancas de comandos específicas de la plataforma que se seleccionan automáticamente en función de la plataforma detectada.

Comandos seguros comunes (todas las plataformas)

• echo - Imprimir texto en la salida estándar

Comandos seguros similares a Unix (macOS/Linux)

• ls - Listar el contenido del directorio
• pwd - Imprimir directorio de trabajo
• echo - Imprimir texto en la salida estándar
• cat - Concatenar e imprimir archivos
• grep - Buscar patrones en archivos
• find - Buscar archivos en una jerarquía de directorios
• cd - Cambiar directorio
• head - Salida de la primera parte de los archivos
• tail - Muestra la última parte de los archivos
• wc - Imprimir recuentos de nuevas líneas, palabras y bytes

Comandos seguros específicos de Windows

• dir - Lista el contenido del directorio
• type - Mostrar el contenido de un archivo de texto
• findstr - Busca cadenas en archivos
• where - Localizar programas
• whoami - Mostrar el usuario actual
• hostname - Nombre de la computadora para mostrar
• ver - Mostrar la versión del sistema operativo

Órdenes que requieren aprobación

Comandos de Windows que requieren aprobación

• copy - Copiar archivos
• move - Mover archivos
• mkdir - Crear directorios
• rmdir - Eliminar directorios
• rename - Cambiar el nombre de los archivos
• attrib - Cambiar atributos de archivo

Comandos de Unix que requieren aprobación

• mv - Mover (renombrar) archivos
• cp - Copiar archivos y directorios
• mkdir - Crear directorios
• touch - Cambiar las marcas de tiempo de los archivos o crear archivos vacíos
• chmod - Cambiar los bits del modo de archivo
• chown - Cambiar el propietario y el grupo del archivo

Órdenes prohibidas

Comandos prohibidos de Windows

• del - Eliminar archivos
• erase - Eliminar archivos
• format - Formatear un disco
• runas - Ejecutar un programa como otro usuario

Comandos prohibidos de Unix

• rm - Eliminar archivos o directorios
• sudo - Ejecutar un comando como otro usuario

Consideraciones de seguridad

• Todos los comandos se ejecutan con los permisos del usuario que ejecuta el servidor MCP
• Los comandos que requieren aprobación se mantienen en una cola hasta que se aprueban explícitamente.
• Los comandos prohibidos nunca se ejecutan
• El servidor utiliza execFile de Node.js en lugar de exec para evitar la inyección de shell
• Los argumentos se validan contra patrones permitidos cuando se especifican

Ampliación de la lista blanca

Puedes ampliar la lista blanca con la herramienta add_to_whitelist . Por ejemplo:

Información del paquete NPM

Super Shell MCP está disponible como un paquete npm en https://www.npmjs.com/package/super-shell-mcp .

Beneficios de usar NPX

El uso del método NPX (como se muestra en la Opción 1 de la sección Configuración) ofrece varias ventajas:

1. Sin configuración manual : no es necesario clonar el repositorio, instalar dependencias ni compilar el proyecto
2. Actualizaciones automáticas : siempre utiliza la última versión publicada
3. Compatibilidad entre plataformas : funciona de la misma manera en Windows, macOS y Linux.
4. Configuración simplificada : configuración más corta sin rutas absolutas
5. Mantenimiento reducido : no hay archivos locales que administrar ni actualizar

Usando desde GitHub

Si prefieres utilizar la última versión de desarrollo directamente desde GitHub:

Publicando tu propia versión

Si desea publicar su propia versión modificada en npm:

1. Actualice el package.json con sus datos
2. Asegúrese de que el campo "bin" esté configurado correctamente:
   "bin": { "super-shell-mcp": "./build/index.js" }
3. Publicar en npm:
   npm publish

Mejores prácticas de NPX

Para una integración óptima con los clientes MCP que utilizan NPX, este proyecto sigue estas prácticas recomendadas:

1. Punto de entrada ejecutable : el archivo principal incluye una línea shebang ( #!/usr/bin/env node ) y se hace ejecutable durante la compilación.
2. Configuración del paquete :
   • "type": "module" - Garantiza que se utilicen los módulos ES
   • Campo "bin" : asigna el nombre del comando al punto de entrada
   • Campo "files" : especifica qué archivos incluir al publicar
   • Script "prepare" : garantiza que la compilación se realice durante la instalación
3. Configuración de TypeScript :
   • "module": "NodeNext" - Compatibilidad adecuada con módulos ES
   • "moduleResolution": "NodeNext" - Consistente con los módulos ES
4. Instalación y ejecución automática :
   • La configuración del cliente MCP utiliza npx -y para instalar y ejecutar automáticamente el paquete
   • Ninguna ventana de terminal está bloqueada ya que el proceso se ejecuta en segundo plano
5. Proceso de publicación :
   # Update version in package.json npm version patch # or minor/major as appropriate # Build and publish npm publish

Estas prácticas garantizan que el cliente MCP pueda iniciar automáticamente el servidor MCP sin necesidad de una ventana de terminal independiente, lo que mejora la experiencia del usuario y la eficiencia operativa.

Solución de problemas

Problemas entre plataformas

Problemas específicos de Windows

1. Política de ejecución de scripts de PowerShell
   • Problema : PowerShell puede bloquear la ejecución del script con el error "La ejecución de scripts está deshabilitada en este sistema".
   • Solución : ejecute PowerShell como administrador y ejecute Set-ExecutionPolicy RemoteSigned o utilice el parámetro -ExecutionPolicy Bypass al configurar el shell.
2. Separadores de ruta
   • Problema : Windows usa barras invertidas ( \ ) en las rutas, que deben escaparse en JSON
   • Solución : utilice barras invertidas dobles ( \\ ) en los archivos de configuración JSON, por ejemplo, C:\\Windows\\System32\\cmd.exe
3. Comando no encontrado
   • Problema : Windows no tiene comandos Unix como ls , grep , etc.
   • Solución : utilice equivalentes de Windows ( dir en lugar de ls , findstr en lugar de grep )

Problemas específicos de macOS/Linux

1. Permisos de Shell
   • Problema : Permiso denegado al ejecutar comandos
   • Solución : asegúrese de que el shell tenga los permisos adecuados con chmod +x /path/to/shell
2. Variables de entorno
   • Problema : Las variables de entorno no están disponibles en el servidor MCP
   • Solución : establezca variables de entorno en el archivo de perfil del shell ( .zshrc , .bashrc , etc.)

Solución de problemas generales

1. Problemas de detección de shell
   • Problema : el servidor no detecta el shell correcto
   • Solución : especifique explícitamente la ruta del shell en la configuración
2. Tiempo de espera de ejecución del comando
   • Problema : los comandos tardan demasiado y se agota el tiempo de espera
   • Solución : Aumente el valor de tiempo de espera en el constructor del servicio de comandos

Sistema de registro

El servidor incluye un sistema de registro integral que escribe registros en un archivo para facilitar la depuración y la supervisión:

1. Ubicación del archivo de registro
   • Predeterminado: logs/super-shell-mcp.log en el directorio del servidor
   • El directorio de registros se crea automáticamente y Git lo rastrea (con un archivo .gitkeep)
   • Los archivos de registro en sí se excluyen de Git a través de .gitignore
   • Contiene información detallada sobre las operaciones del servidor, la ejecución de comandos y el flujo de trabajo de aprobación.
2. Niveles de registro
   • INFO : Información operativa general
   • DEBUG : Información de depuración detallada
   • ERROR : Condiciones de error y excepciones
3. Visualización de registros
   • Utilice los comandos de visualización de archivos estándar para comprobar los registros:
     # View the entire log cat logs/super-shell-mcp.log # Follow log updates in real-time tail -f logs/super-shell-mcp.log
4. Contenido del registro
   • Inicio y configuración del servidor
   • Solicitudes y resultados de ejecución de comandos
   • Eventos de flujo de trabajo de aprobación (pendiente, aprobado, denegado)
   • Condiciones de error e información de solución de problemas
5. Gestión de listas blancas
   • Problema : Es necesario agregar comandos personalizados a la lista blanca
   • Solución : utilice la herramienta add_to_whitelist para agregar comandos específicos para su entorno

Licencia

Este servidor MCP cuenta con la licencia MIT. Esto significa que puede usar, modificar y distribuir el software libremente, sujeto a los términos y condiciones de la licencia MIT. Para más detalles, consulte el archivo de LICENCIA en el repositorio del proyecto.