# tumf/mcp-shell-server [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/tumf/mcp-shell-server  
**GitHub Stars:** 192  
**npm Downloads (last month):** 258  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/tumf-mcp-shell-server

## Description
A secure shell command execution server implementing the Model Context Protocol (MCP)

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-shell-server": {
    "command": "npx",
    "args": ["-y","@smithery/cli"],
    "env": {
      "ALLOW_COMMANDS": "",
      "ALLOWED_COMMANDS": "",
      "ALLOW_PATTERNS": "",
      "MCP_SHELL_CHILD_ENV_ALLOWLIST": ""
    }
  }
}
```

**Requires environment variables:** `ALLOW_COMMANDS`, `ALLOWED_COMMANDS`, `ALLOW_PATTERNS`, `MCP_SHELL_CHILD_ENV_ALLOWLIST` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/tumf-mcp-shell-server/readme_