MCP Shell Server

What tumf/mcp-shell-server MCP server does

The tumf/mcp-shell-server MCP server lets an MCP client request shell command execution against a configured allowlist. Commands are represented as argument arrays, which avoids interpreting a single shell command string. The response includes standard output, standard error, the process status, and execution time.

Requests can provide stdin, a working directory, and a timeout. If no directory is supplied, execution uses the working directory of the process that launched the server. Relative directories are resolved from that location, not from the MCP client’s current directory.

How it works

Allowed command names can be listed with ALLOW_COMMANDS or its ALLOWED_COMMANDS alias. ALLOW_PATTERNS accepts comma-separated regular expressions that match command names with full-match semantics. These settings control command names, not unrestricted argument-level behavior.

The server executes commands through subprocess argv handling. Pipelines validate each argv segment without invoking a shell. Input and output redirection using <, >, and >> is contained within the requested working directory. Server-side defaults enforce a timeout, a maximum timeout, and output byte limits.

Child processes receive a reduced environment rather than the complete environment of the server. POSIX launches include PATH by default; selected additional variables can be forwarded with MCP_SHELL_CHILD_ENV_ALLOWLIST. Audit events record execution results and metadata, while omitting raw output and redacting secret-like arguments and environment values.

Setup and configuration

The published package can be installed with pip install mcp-shell-server or launched with uvx mcp-shell-server. A typical launch sets an allowlist, for example ALLOW_COMMANDS="ls,cat,echo" uvx mcp-shell-server. The README also provides a Claude Desktop configuration using uvx and the mcp-shell-server package.

Configure only the commands the client needs. Pattern entries must describe command names and cannot contain whitespace or shell metacharacters. The child environment allowlist uses exact variable names, separated by commas.

Tools and capabilities

The tumf/mcp-shell-server MCP server supports:

• Allowlisted command execution with argv arguments
• Stdin input and structured stdout/stderr results
• Optional working directories and execution timeouts
• Validated pipelines and directory-contained redirection
• Output-size limits and process termination on timeout or cap violations
• Structured audit events for success, rejection, timeout, output-cap, and process-error outcomes
• Minimal child environments with optional variable forwarding

Limitations and notes

Allowlisting a command name does not sandbox every feature of that program. The server rejects several known execution and escape patterns, including shell or interpreter launchers, selected find, awk, tar, git, sort, and wrapper-tool options, but describes this protection as defense in depth rather than a complete sandbox. For untrusted clients or broad command lists, run the server inside an OS or container sandbox with least-privilege filesystem and network access.

Audit logs contain metadata rather than command output. Secret-like names and values are redacted, and long non-numeric values may be represented by a short SHA-256 digest.