MCP Shell

What sonirico/mcp-shell MCP server does

The sonirico/mcp-shell MCP server gives an MCP-compatible agent one tool for executing shell commands. The tool requires a command string and accepts an optional base64 boolean that encodes standard output and standard error in the response. Results include the command, status, exit code, stdout, stderr, and execution time; security details may also be returned.

It is intended for situations where an agent needs access to command-line utilities while the operator retains control over which commands can run. Docker is supported as a deployment option, and the example mounts a workspace into the container.

How it works

By default, the server starts in secure mode even when no configuration file is present. This mode does not invoke a shell interpreter. It parses the input and accepts only one fully literal simple command, rejecting shell features such as pipes, command lists, substitutions, redirections, and globs.

Allowed executables must be listed in policy and must also be classified as safe. Built-in examples include read-oriented utilities such as ls, cat, grep, find, head, and tail. Some commands, including git, find, sort, and uniq, use argument policies that permit only explicitly approved options or operations. Interpreters and wrappers such as bash, python, env, timeout, and xargs are rejected in secure mode, even if added to the allowlist.

The policy can also set blocked argument patterns, a maximum execution duration, a maximum output size, a working directory, and audit logging. The sonirico/mcp-shell MCP server can therefore apply command and resource restrictions before execution, but secure mode is an early-rejection layer rather than a complete sandbox.

Setup and configuration

The project provides a Docker image and a source-based installation path. A basic Docker invocation is:

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

When building from source, the documented sequence clones the repository, runs make install, and starts mcp-shell.

Set MCP_SHELL_SEC_CONFIG_FILE to load a YAML security policy instead of relying on the built-in secure defaults. MCP_SHELL_ALLOW_UNSAFE=true disables validation and permits unrestricted execution; the project explicitly warns against using this setting in production. Logging can be adjusted with MCP_SHELL_LOG_LEVEL, MCP_SHELL_LOG_FORMAT, and MCP_SHELL_LOG_OUTPUT.

Claude Desktop can connect through a Docker stdio configuration. A custom policy file can be mounted into the container and selected with MCP_SHELL_SEC_CONFIG_FILE.

Tools and capabilities

The sonirico/mcp-shell MCP server provides one shell-command execution tool with these inputs:

• command: required command text.
• base64: optional boolean for encoding stdout and stderr.

Configuration supports executable allowlists, command-string policies in legacy mode, blocked patterns, execution timeouts, output limits, working-directory selection, and audit logging. Secure mode is the recommended policy. Legacy mode enables shell execution and uses allowlists or blocklists over command strings, so its injection risk depends on the policy.

Limitations and notes

Unrestricted execution is available only through an explicit environment-variable opt-in and is dangerous outside local development. Secure mode does not itself provide process isolation. The Docker image runs as a non-root user on Alpine, but the documentation recommends additional operating-system controls such as a read-only filesystem and dropped capabilities for defense in depth.

Git handling is restricted to read-only subcommands, with diff and text conversion drivers suppressed and a minimal environment. Child processes do not inherit server or .env secrets. The repository directs users to its security documentation for the detailed threat model and vulnerability-reporting scope.