shell

The shell-mcp MCP server provides a secure, policy-driven interface for executing shell commands via the MCP protocol. It offers advanced command whitelisting with flexible allow/deny policies, user confirmation for non-whitelisted commands via elicitation when supported by the client, and a suite of shell feature restrictions (such as pipes, redirects, and substitutions) to prevent unsafe operations. The server can operate over multiple transports (stdio, SSE, and streamable HTTP) and includes timeout protection to avoid hanging processes. It parses input into an AST for thorough validation before generating safe shell code, and provides detailed, context-aware error messages to guide agents and developers.

To use it, start the server with a supported transport, such as the default stdio transport or one of the web-enabled options. With the MCP tool, you can issue commands, inspect results, and rely on the built-in security policies to determine whether a command is allowed, blocked, or requires elicitation. The server reports back structured results and error information that helps LLM agents understand policy decisions and adjust their behavior accordingly.

Prerequisites:

• A Unix-like environment with Rust toolchain and/or Nix installed (depending on your preferred installation method).
• Optional: Docker if you want to run via container.

Install via Nix (recommended for quick, isolated runs):

nix run github:zatevakhin/shell-mcp

Or run a specific version/tag:

nix run "github:zatevakhin/shell-mcp?ref=<tag|branch|rev>"

Install via Cargo (builds from source):

cargo install --git https://github.com/zatevakhin/shell-mcp.git

Run the server (after installation):

# Default stdio transport
shell-mcp

# Run with SSE transport
shell-mcp --transport sse --bind 127.0.0.1:3003

# Run with streamable HTTP
shell-mcp --transport streamable-http --bind 127.0.0.1:3003

If you prefer Docker, you can use:

docker run -i zatevakhin/shell-mcp

Notes:

• The README describes multiple transport options; choose the one that best fits your deployment.
• If you need to adjust security policies, configure environment variables as shown in the README (e.g., SHELL_COMMANDS, SHELL_DISABLED_COMMANDS, SHELL_DISABLE_FEATURES, etc.).

Tips and common considerations:

• Start with a conservative default policy (e.g., Traditional Whitelist) and gradually widen allowed commands as needed.
• Use the timeout setting (SHELL_MCP_TIMEOUT) to prevent hanging shell processes; the default is 30 seconds.
• If you enable verbose logging (-v or -vv), note that logs are written to stderr and that RUST_LOG can affect log verbosity beyond CLI flags.
• For client integrations, prefer elicitation for non-whitelisted commands if the client supports MCP elicitation; this helps maintain policy compliance while enabling broader functionality.
• Be mindful of shell feature controls (pipes, substitutions, etc.) to ensure commands cannot leverage unsafe capabilities in your environment.
• If you run into issues, check startup information and the Shell Features Status to verify which features are enabled or disabled.