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

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/tumf/mcp-shell-server  
**GitHub Stars:** 201  
**Views:** 5  
**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)

## Tools
Capabilities this server exposes over MCP:

- **shell_execute** — Execute a shell command
Allowed commands: 
Allowed patterns: 
Default timeout: 30s; maximum timeout: 300s; output cap: 1048576 bytes

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

```json
"mcpServers": {
  "mcp-shell-server": {
    "command": "uvx",
    "args": ["mcp-shell-server"],
    "env": {
      "ALLOW_COMMANDS": "",
      "ALLOWED_COMMANDS": "",
      "ALLOW_PATTERNS": ""
    }
  }
}
```

**Requires environment variables:** `ALLOW_COMMANDS`, `ALLOWED_COMMANDS`, `ALLOW_PATTERNS` — 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 provides one MCP tool, `shell_execute`, for running approved local commands. Commands are started as argument arrays rather than shell-interpreted strings. The result includes standard output, standard error, exit status, and execution time.

Command execution can receive data through stdin. The server also supports pipelines while retaining argv validation for each segment. Its redirection handling covers `<`, `>`, and `>>`; redirected paths must remain under the requested working directory.

## How it works

The server checks the command name against an explicit allowlist or regular-expression patterns before creating a subprocess. `ALLOW_COMMANDS` accepts comma-separated command names, while `ALLOW_PATTERNS` accepts comma-separated regular expressions matched against command names with full-match semantics. `ALLOWED_COMMANDS` is available as an alias for `ALLOW_COMMANDS`.

Execution has a 30-second default timeout, a maximum timeout of 300 seconds, and a 1,048,576-byte output limit. Child processes receive a minimal allowlisted environment rather than the server's complete environment. Structured audit records cover successful execution, rejected requests, timeouts, output-limit events, and process errors, with redaction.

These controls govern the server's own process creation; they do not sandbox an approved program. An allowed executable still runs with the server process's operating-system identity, filesystem access, network access, and available credentials. Programs may also start descendants, interpret arguments, read configuration, or access files independently of server-managed redirection.

## Setup and configuration

Install the package with `pip install mcp-shell-server`, or start the published package with `uvx mcp-shell-server`. A typical launch sets an allowlist, for example `ALLOW_COMMANDS="ls,cat,echo" uvx mcp-shell-server`. Command names may contain optional spaces around comma separators.

The published configuration runs `uvx mcp-shell-server`; the local form uses `uv --directory . run mcp-shell-server`. Smithery also provides an installation command for Claude Desktop.

Keep the allowlist narrow. Pattern entries describe command names only, not complete shell commands or argument policies. The implementation additionally rejects documented command and argument forms associated with launching other programs, shell escapes, external Git configuration or execution, and similar vectors. These checks are defense in depth rather than a safety proof.

## Tools and capabilities

- `shell_execute`: execute an allowlisted command with optional arguments and stdin.
- Return stdout, stderr, exit status, and elapsed execution time.
- Run validated argv-based pipelines without invoking a shell string.
- Apply server-side timeout and output-byte limits.
- Handle redirection within the requested working directory.
- Record structured, redacted execution outcomes.

For requests or reachable files containing model-generated, fetched, issue, or repository-derived content, deploy the tumf/mcp-shell-server MCP server inside an independently enforced container, VM, jail, or OS policy. The recommended boundary includes a non-root identity, restricted filesystem and network access, no ambient credentials, descendant-process containment, and external CPU, memory, disk, process, and wall-clock limits.

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