local-only server

The server can only run on the client’s local machine because it depends on local resources.

Integrations

Code coverage reporting integration shown by the codecov badge in the README header, displaying test coverage metrics for the project.

Servidor Shell MCP

Un servidor de ejecución de comandos de shell seguro que implementa el Protocolo de Contexto de Modelo (MCP). Este servidor permite la ejecución remota de comandos de shell autorizados, compatibles con la entrada estándar.

Características

Ejecución segura de comandos : solo se pueden ejecutar los comandos incluidos en la lista blanca
Soporte de entrada estándar : pasa la entrada a los comandos a través de la entrada estándar
Salida completa : devuelve stdout, stderr, estado de salida y tiempo de ejecución
Seguridad del operador 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

Configuración del cliente MCP en su 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

Configuración

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

Uso

Iniciando el servidor

ALLOW_COMMANDS="ls,cat,echo" uvx mcp-shell-server
# Or using the 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 por comas con espacios opcionales.

Formatos válidos para ALLOW_COMMANDS o ALLOWED_COMMANDS:

ALLOW_COMMANDS="ls,cat,echo"          # Basic format
ALLOWED_COMMANDS="ls ,echo, cat"      # With spaces (using alias)
ALLOW_COMMANDS="ls,  cat  , echo"     # Multiple spaces

Formato de solicitud

# Basic command execution
{
    "command": ["ls", "-l", "/tmp"]
}

# Command with stdin input
{
    "command": ["cat"],
    "stdin": "Hello, World!"
}

# Command with timeout
{
    "command": ["long-running-process"],
    "timeout": 30  # Maximum execution time in seconds
}

# Command with working directory and timeout
{
    "command": ["grep", "-r", "pattern"],
    "directory": "/path/to/search",
    "timeout": 60
}

Formato de respuesta

Respuesta exitosa:

{
    "stdout": "command output",
    "stderr": "",
    "status": 0,
    "execution_time": 0.123
}

Respuesta de error:

{
    "error": "Command not allowed: rm",
    "status": 1,
    "stdout": "",
    "stderr": "Command not allowed: 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	Requerido	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 la ejecución de comandos
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 estándar del 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 (solo aparece si falla)

Requisitos

Python 3.11 o superior
mcp>=1.1.0

Licencia

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

You must be authenticated.

A

security – no known vulnerabilities

A

license - permissive license

A

quality - confirmed to work

Tools

shell_execute