Servidor Shell MCP

Un servidor seguro para ejecutar comandos de shell que implementa el Protocolo de Contexto de Modelo (MCP). Este servidor permite la ejecución remota de comandos de shell autorizados con soporte para entrada a través de stdin.

Características

Ejecución segura de comandos : solo se pueden ejecutar comandos autorizados
Soporte de entrada estándar : pasa la entrada a los comandos a través de la entrada estándar
Salida completa : devuelve stdout, stderr, código de salida y tiempo de ejecución
Seguridad con operadores de shell : valida los comandos después de los operadores de shell (;, &&, ||, |)
Control de tiempo de espera : establece el tiempo máximo de ejecución de los comandos

Configurando el cliente MCP en tu Claude.app

Versión publicada

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "shell": {
      "command": "uvx",
      "args": [
        "mcp-shell-server"
      ],
      "env": {
        "ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find"
      }
    },
  }
}

Versión local

Ajustes

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "shell": {
      "command": "uv",
      "args": [
        "--directory",
        ".",
        "run",
        "mcp-shell-server"
      ],
      "env": {
        "ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find"
      }
    },
  }
}

Instalación

pip install mcp-shell-server

Usar

Iniciando el servidor

ALLOW_COMMANDS="ls,cat,echo" uvx mcp-shell-server
# Ou usando o alias
ALLOWED_COMMANDS="ls,cat,echo" uvx mcp-shell-server

La variable de entorno ALLOW_COMMANDS (o su alias ALLOWED_COMMANDS ) especifica qué comandos se pueden ejecutar. Los comandos se pueden separar mediante comas con espacios opcionales alrededor de ellos.

Formatos válidos para ALLOW_COMMANDS o ALLOWED_COMMANDS:

ALLOW_COMMANDS="ls,cat,echo"          # Formato básico
ALLOWED_COMMANDS="ls ,echo, cat"      # Com espaços (usando alias)
ALLOW_COMMANDS="ls,  cat  , echo"     # Múltiplos espaços

Formato de solicitud

# Execução básica de comando
{
    "command": ["ls", "-l", "/tmp"]
}

# Comando com entrada stdin
{
    "command": ["cat"],
    "stdin": "Hello, World!"
}

# Comando com timeout
{
    "command": ["long-running-process"],
    "timeout": 30  # Tempo máximo de execução em segundos
}

# Comando com diretório de trabalho e timeout
{
    "command": ["grep", "-r", "pattern"],
    "directory": "/path/to/search",
    "timeout": 60
}

Formato de respuesta

Respuesta exitosa:

{
    "stdout": "saída do comando",
    "stderr": "",
    "status": 0,
    "execution_time": 0.123
}

Respuesta de error:

{
    "error": "Comando não permitido: rm",
    "status": 1,
    "stdout": "",
    "stderr": "Comando não permitido: rm",
    "execution_time": 0
}

Seguridad

El servidor implementa varias medidas de seguridad:

Lista blanca de comandos : solo se pueden ejecutar comandos explícitamente permitidos
Validación del operador de shell : los comandos después de los operadores de shell (;, &&, ||, |) también se validan con la lista blanca
Sin inyección de shell : los comandos se ejecutan directamente sin interpretación de shell

Desarrollo

Configuración del entorno de desarrollo

Clonar el repositorio

git clone https://github.com/yourusername/mcp-shell-server.git
cd mcp-shell-server

Instalar dependencias, incluidos los requisitos de prueba

pip install -e ".[test]"

Ejecución de pruebas

pytest

Referencia de API

Argumentos de solicitud

Campo	Tipo	Obligatorio	Descripción
dominio	cadena[]	Sí	Comando y sus argumentos como elementos de matriz
entrada estándar	cadena	No	Entrada que se pasará al comando
directorio	cadena	No	Directorio de trabajo para ejecutar el comando
se acabó el tiempo	entero	No	Tiempo máximo de ejecución en segundos

Campos de respuesta

Campo	Tipo	Descripción
salida estándar	cadena	Salida estándar del comando
error de error estándar	cadena	Salida de error de comando
estado	entero	Código de estado de salida
tiempo de ejecución	flotar	Tiempo de ejecución (en segundos)
error	cadena	Mensaje de error (presente sólo si falló)

Requisitos

Python 3.11 o superior
mcp>=1.1.0

Licencia

Licencia MIT: consulte el archivo LICENCIA para obtener más detalles