mcp-shell-sudo

Servidor MCP para Linux escrito en Python que ejecuta comandos locales usando argv, soporta sudo no interactivo mediante PASSWORD_SUDO, proporciona una lista de comandos permitidos opcional mediante ALLOW_COMMANDS, y puede confinar las escrituras del sistema de archivos a WORK_DIR usando Bubblewrap.

Requisitos

• Linux.

• Python 3.11+.

• uv recomendado.

• MCP Python SDK 2.0.0.

• sudo si se ejecutarán comandos elevados.

• bubblewrap si WORK_DIR está configurado.

En Debian/Ubuntu:

sudo apt update
sudo apt install -y bubblewrap

Related MCP server: MCP Process Server

Variables de Entorno

PASSWORD_SUDO

Contraseña del usuario que ejecuta el servidor MCP.

• Vacía o sin configurar: el servidor nunca inventa ni solicita interactivamente una contraseña. Los comandos con prefijo sudo se ejecutan usando sudo -n y solo funcionarán si ya existe una credencial en caché válida o si está configurada una regla NOPASSWD.

• Configurada: sudo se ejecuta con -S, y la contraseña se proporciona a través de stdin, nunca a través de argv o registros.

Ejemplo:

"PASSWORD_SUDO": "my-password"

La forma admitida es:

["sudo", "id"]

Las banderas personalizadas de sudo como sudo -u postgres ... no se aceptan. Esto evita que la capa de políticas tenga que interpretar la gramática completa del comando sudo.

WORK_DIR

Directorio de trabajo opcional.

• Vacío o sin configurar: el servidor MCP puede trabajar desde cualquier directorio existente especificado en la llamada a la herramienta.

• Configurado: el servidor entra en modo estricto. directory debe resolverse dentro de WORK_DIR, y cada proceso se ejecuta dentro de un espacio de nombres de montaje de Bubblewrap donde / es de solo lectura, WORK_DIR está montado de lectura-escritura, y /tmp y /run son temporales.

Usar cwd solo no sería suficiente para garantizar este aislamiento. Un proceso aún podría escribir en /etc, /home/..., o seguir enlaces simbólicos fuera del proyecto. Por esta razón, el servidor falla al inicio si WORK_DIR está configurado pero bwrap no está disponible.

En este modo, sudo se rechaza porque la elevación de privilegios a nivel de host sería incompatible con la garantía de que las escrituras del sistema de archivos permanezcan confinadas al espacio de trabajo.

ALLOW_COMMANDS

Lista de nombres de ejecutables separados por comas.

"ALLOW_COMMANDS": "git,ls,cat,grep,python,node,pnpm"

• Vacío o sin configurar: todos los ejecutables están permitidos.

• Configurado: solo se permiten nombres de ejecutables exactos de la lista, y deben invocarse por nombre en lugar de mediante rutas como /usr/bin/git.

• Si el comando comienza con sudo, se valida el ejecutable real que sigue a sudo.

La lista de permitidos se aplica a ejecutables, no a argumentos. Permitir bash, python, node, env u otra herramienta capaz de ejecutar procesos expande significativamente lo que el cliente MCP puede hacer.

Instalación

uv sync

Para desarrollo:

uv sync --extra dev

Ejecución Manual

uv run mcp-shell-sudo

El transporte es stdio. Los registros nunca se escriben en stdout para evitar corromper los mensajes JSON-RPC; los registros se escriben en stderr.

Configuración de MCP

Ejemplo con comandos sin restricciones y sudo habilitado:

{
  "mcpServers": {
    "shell": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/mcp-shell-sudo",
        "run",
        "mcp-shell-sudo"
      ],
      "env": {
        "PASSWORD_SUDO": "YOUR_PASSWORD",
        "WORK_DIR": "",
        "ALLOW_COMMANDS": ""
      }
    }
  }
}

Ejemplo confinado a un proyecto específico:

{
  "mcpServers": {
    "shell-project": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/mcp-shell-sudo",
        "run",
        "mcp-shell-sudo"
      ],
      "env": {
        "PASSWORD_SUDO": "",
        "WORK_DIR": "/home/user/projects/app",
        "ALLOW_COMMANDS": "git,ls,cat,grep,find,python,node,pnpm"
      }
    }
  }
}

Herramienta shell_execute

Entrada básica:

{
  "command": ["ls", "-la"]
}

Con un directorio de trabajo:

{
  "command": ["git", "status"],
  "directory": "backend"
}

Con stdin:

{
  "command": ["cat"],
  "stdin": "hello\n"
}

Con sudo:

{
  "command": ["sudo", "id"]
}

Respuesta:

{
  "stdout": "uid=0(root) gid=0(root) groups=0(root)\n",
  "stderr": "",
  "status": 0,
  "execution_time": 0.031,
  "timed_out": false,
  "output_limited": false
}

Herramienta shell_config

Devuelve la configuración efectiva no secreta.

Nunca devuelve PASSWORD_SUDO; solo indica si se ha configurado una contraseña de sudo.

Medidas de Seguridad Implementadas

• Usa create_subprocess_exec; no usa shell=True.

• command se pasa como un array argv explícito.

• La contraseña de sudo nunca aparece en argv, respuestas, registros ni en el entorno del proceso hijo.

• Si PASSWORD_SUDO no está configurado, sudo -n evita que el proceso se cuelgue esperando un prompt interactivo de contraseña.

• ALLOW_COMMANDS valida el ejecutable real que sigue a una invocación simple de sudo.

• Usa un PATH fijo y reducido para evitar resolver ejecutables desde . o rutas heredadas arbitrarias.

• Usa un entorno hijo reducido en lugar de heredar todo el entorno del servidor MCP.

• Tiempo de espera por llamada: 60 segundos por defecto, con un máximo de 600 segundos.

• Límite de salida: 2 MiB por flujo. Si se supera el límite, se termina todo el grupo de procesos.

• Los procesos se ejecutan en una nueva sesión y todo el grupo de procesos se termina al agotarse el tiempo de espera.

• WORK_DIR usa Bubblewrap y falla de forma segura si no se puede proporcionar aislamiento.

Limitaciones Importantes

1. ALLOW_COMMANDS="" significa ejecución arbitraria de comandos con los permisos del usuario que ejecuta el servidor MCP. Si PASSWORD_SUDO también está configurado, el cliente MCP puede solicitar acciones como root. Use esta configuración solo con un cliente y modelo que usted controle.

2. Una lista de permitidos de ejecutables no valida semánticamente los argumentos de los comandos. python, node, bash, sh, perl y herramientas similares son efectivamente equivalentes a permitir la ejecución de código arbitrario.

3. WORK_DIR confina las ubicaciones del sistema de archivos que son escribibles, pero no está diseñado para comportarse como una VM o un sandbox de red. Un comando con acceso a red aún puede modificar recursos remotos para los que tenga credenciales válidas.

4. PASSWORD_SUDO almacenado en la configuración del cliente MCP sigue siendo un secreto almacenado en ese archivo. Restrinja los permisos del archivo con chmod 600 y nunca lo envíe al control de versiones.

Pruebas

uv run --extra dev pytest
uv run --extra dev ruff check .