MCP Shell

mcp-shell

Servidor MCP que ejecuta comandos de shell. Tu LLM obtiene una herramienta; tú controlas qué se ejecuta y cómo.

Construido sobre mark3labs/mcp-go. Escrito en Go.

---

Ejecutarlo

Docker (lo más fácil):

docker run -it --rm -v /tmp/mcp-workspace:/tmp/mcp-workspace sonirico/mcp-shell:latest

Desde el código fuente:

git clone https://github.com/sonirico/mcp-shell && cd mcp-shell
make install
mcp-shell

---

Configurarlo

El modo seguro es el predeterminado. Sin archivo de configuración, mcp-shell arranca en modo seguro y registra solo herramientas tipadas: lecturas de archivos, grep/glob, inspección de git, y (opt-in) escrituras de archivos/git y scripts definidos por el operador. No hay comando de shell sin procesar. Solo necesitas un archivo de configuración para cambiar los valores predeterminados a continuación. Para ejecutar completamente sin restricciones, debes optar explícitamente:

MCP_SHELL_ALLOW_UNSAFE=1 mcp-shell   # disables secure mode; the only tool is shell_exec

Para personalizar la política, apunta a una configuración YAML:

export MCP_SHELL_SEC_CONFIG_FILE=/path/to/security.yaml
mcp-shell

Modo seguro (predeterminado) — solo herramientas tipadas, cada ruta confinada a working_directory:

security:
  enabled: true
  working_directory: /tmp/mcp-workspace
  max_execution_time: 30s
  max_output_size: 1048576
  run_as_user: ""
  audit_log: true

  # Expose file and git write tools (write_file, edit_file, mkdir, move,
  # delete, git_add, git_commit, git_switch, git_restore, git_stash). Off by
  # default.
  writes_enabled: false

  # Operator-defined scripts exposed through the run_script tool. The client
  # picks a name; the argv is yours and cannot be altered.
  # scripts:
  #   test: ["go", "test", "./..."]
  #   lint: ["golangci-lint", "run"]

---

Conectarlo

Claude Desktop — agrega a tu configuración de MCP:

{
  "mcpServers": {
    "shell": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "sonirico/mcp-shell:latest"],
      "env": { "MCP_SHELL_LOG_LEVEL": "info" }
    }
  }
}

Para una configuración personalizada, monta el archivo y establece la variable de entorno:

{
  "command": "docker",
  "args": ["run", "--rm", "-i", "-v", "/path/to/security.yaml:/etc/mcp-shell/security.yaml", "-e", "MCP_SHELL_SEC_CONFIG_FILE=/etc/mcp-shell/security.yaml", "sonirico/mcp-shell:latest"]
}

---

Herramientas

El modo seguro (el predeterminado) registra estas herramientas tipadas. * marca un parámetro obligatorio.

Herramienta	Parámetros	Disponibilidad
read_file	path*, offset, limit, tail	siempre
list_dir	path, depth, include_hidden	siempre
glob	pattern*, path, newer_than, max_results	siempre
grep	pattern*, path, glob, ignore_case, context, files_only, count, max_results	siempre
stat	path*	siempre
diff_files	path_a*, path_b*	siempre
system_info		siempre
git_status		siempre
git_log	max_count, ref, path, author, grep, since, until, oneline, follow	siempre
git_diff	ref, ref_to, staged, path, stat_only, name_only	siempre
git_show	ref, path, stat_only	siempre
git_blame	path*, ref, line_start, line_end	siempre
git_branches	all, merged	siempre
git_tags	pattern	siempre
git_rev_parse	ref*	siempre
git_ls_files	path, untracked	siempre
git_stash_list		siempre
git_remotes		siempre
write_file	path*, content*, append	writes_enabled
edit_file	path*, old_string*, new_string*, replace_all	writes_enabled
mkdir	path*	writes_enabled
move	from*, to*	writes_enabled
delete	path*, recursive	writes_enabled
git_add	paths, all	writes_enabled
git_commit	message*, all	writes_enabled
git_switch	branch*, create	writes_enabled
git_restore	paths*, staged	writes_enabled
git_stash	action*, message	writes_enabled
run_script	name*	scripts

Cada parámetro de ruta se resuelve contra working_directory (se siguen los enlaces simbólicos); cualquier cosa fuera de eso se rechaza. Las rutas y referencias de git se pasan posicionalmente y se validan: una referencia que comience con - se rechaza. No hay herramientas de red; push, fetch y clone no se ofrecen.

Modo sin restricciones: shell_exec existe solo con MCP_SHELL_ALLOW_UNSAFE=1, ejecuta el comando a través de bash -c sin validación, por diseño, y es la única herramienta registrada en ese modo.

---

Variables de entorno

Variable	Descripción
MCP_SHELL_SEC_CONFIG_FILE	Ruta al YAML de seguridad (anula los valores seguros predeterminados integrados)
MCP_SHELL_ALLOW_UNSAFE	Establece 1 (o true) para deshabilitar el modo seguro y exponer shell_exec en lugar de las herramientas tipadas (opt-in)
MCP_SHELL_SERVER_NAME	Nombre del servidor (predeterminado: "mcp-shell 🐚")
MCP_SHELL_LOG_LEVEL	debug, info, warn, error, fatal
MCP_SHELL_LOG_FORMAT	json, console
MCP_SHELL_LOG_OUTPUT	stdout, stderr, file

---

Desarrollo

make install dev-tools   # deps + goimports, golines
make fmt test lint
make docker-build       # build image locally
make release            # binary + docker image

---

Seguridad

• Predeterminado: Modo seguro. El servidor construye el argv de cada comando por sí mismo; el cliente nunca proporciona una cadena de shell. Solo se registran herramientas tipadas.
• Confinamiento de rutas: cada parámetro de ruta se resuelve contra working_directory, se siguen los enlaces simbólicos, y cualquier cosa que se resuelva fuera de eso se rechaza.
• Refuerzo de Git: las rutas se pasan después de --, las referencias después de --end-of-options, y una referencia que comience con - se rechaza. Git se ejecuta con GIT_CONFIG_NOSYSTEM=1, GIT_CONFIG_GLOBAL=/dev/null, core.fsmonitor, core.pager y core.hooksPath neutralizados, y --no-ext-diff --no-textconv en log/diff/show/blame.
• Entorno mínimo: los procesos hijos reciben solo PATH, HOME y LANG, nunca el entorno del propio servidor ni los secretos de .env.
• Escrituras y scripts son opt-in: writes_enabled: true expone las herramientas de escritura de archivos/git; un mapa scripts no vacío expone run_script. Ambos están desactivados por predeterminado.
• Sin restricciones: solo a través de MCP_SHELL_ALLOW_UNSAFE=1. La única herramienta registrada es shell_exec, que ejecuta bash -c sin validación. Está bien para desarrollo local, peligroso en otros casos.
• Docker: Se ejecuta como no root, basado en Alpine. Úsalo en producción. Mejor combinado con un sandbox del sistema operativo (sistema de archivos de solo lectura, capacidades eliminadas) como defensa en profundidad.

El modelo de amenazas, las garantías y el alcance para informes de vulnerabilidades están en SECURITY.md. Léelo antes de abrir un aviso.

---

Migración desde 0.x

El modo seguro ya no valida una cadena de comando shell_exec; expone herramientas tipadas en su lugar. El bloque security: de un archivo de configuración ya no acepta:

Clave eliminada	Reemplazo
use_shell_execution	no es necesario; las herramientas tipadas nunca ejecutan shell
allowed_executables	no es necesario; cada herramienta ejecuta un argv fijo construido por el servidor
allowed_commands	no es necesario; igual que arriba
blocked_commands	no es necesario; igual que arriba
blocked_patterns	no es necesario; igual que arriba

Cargar un archivo de configuración que aún establezca una de estas falla al inicio con un error que nombra la clave. Ya no hay "modo legado" ni ejemplo de security-legacy.yaml. Si necesitas acceso de shell sin procesar, establece MCP_SHELL_ALLOW_UNSAFE=1 para recuperar shell_exec; ya no está restringido por el bloque security: en absoluto.

---

Contribuir

Haz un fork, crea una rama, make fmt test, abre un PR.