mcp-shell

mcp-shell provides a controlled shell command tool for an MCP server. It runs shell commands issued by your LLM or automation layer and returns structured outputs including status, exit code, stdout, stderr, and timing information. You can configure either a secure mode (recommended) where only specific executables are allowed and shell interpretation is disabled, or a legacy mode with shell execution and allowlist/blocklist by exact command strings. The Docker image is portable and includes an Alpine-based runtime with non-root execution for production usage. To integrate with a client, wire up the mcp-shell server in your MCP config and invoke commands through the Tool API, which accepts a command string and optional base64 encoding of stdout/stderr. Be mindful of security settings: in secure mode, the tool will only permit whitelisted executables and will not interpret shell commands, reducing injection risk. In legacy mode, shell parsing is enabled, so carefully manage allowlists and patterns to avoid injection vulnerabilities.

Prerequisites

• Docker (recommended) or Go toolchain for building from source
• Basic shell and Git access

Installation steps (Docker-based)

1. Ensure Docker is installed and running
2. Run the MCP shell container as a long-running or ephemeral service: docker run -it --rm -v /tmp/mcp-workspace:/tmp/mcp-workspace sonirico/mcp-shell:latest

Alternative: install from source (Go)

1. Install Go from https://golang.org/dl/
2. Clone the repository: git clone https://github.com/sonirico/mcp-shell && cd mcp-shell
3. Build and run: make install mcp-shell

Configuration (security)

• To enable secure mode, provide a YAML config path via MCP_SHELL_SEC_CONFIG_FILE and start the server: export MCP_SHELL_SEC_CONFIG_FILE=/path/to/security.yaml mcp-shell

Environment variables (optional)

• MCP_SHELL_SEC_CONFIG_FILE: Path to security YAML
• MCP_SHELL_SERVER_NAME: Server name (default: "mcp-shell 🐚")
• MCP_SHELL_LOG_LEVEL: log level (debug, info, warn, error, fatal)
• MCP_SHELL_LOG_FORMAT: json or console
• MCP_SHELL_LOG_OUTPUT: stdout, stderr, or file

Tips and caveats:

• Secure mode is recommended for production to prevent arbitrary command execution; when enabled, only whitelisted executables are allowed and shell interpretation is disabled.
• If you mount a custom security.yaml, ensure correct path mappings and environment variable MCP_SHELL_SEC_CONFIG_FILE is set accordingly.
• The Docker setup runs as non-root inside the container; if you need file workspace persistence, mount a host directory to /tmp/mcp-workspace as shown in examples.
• When debugging, enable MCP_SHELL_LOG_LEVEL=debug and set MCP_SHELL_LOG_FORMAT=json to capture structured logs.
• For performance and isolation, prefer Docker deployments in multi-tenant environments and avoid running with elevated privileges.