Log inSubmit server
MCP Shell Server logo

MCP Shell Server

by tumf

Runs allowlisted shell commands over MCP with argv execution, limits, redirection controls, and audit logging.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install MCP Shell Server

Pick your client, then add it in one click or paste the config.

STDIOPython
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "tumf-mcp-shell-server": {
      "command": "uvx",
      "args": [
        "mcp-shell-server"
      ],
      "env": {
        "ALLOW_COMMANDS": "YOUR_VALUE_HERE",
        "ALLOWED_COMMANDS": "YOUR_VALUE_HERE",
        "ALLOW_PATTERNS": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Install not yet sandbox-tested— the server itself is confirmed live (we called its tools/list endpoint). The stdio install command is a separate, ongoing check.

Overview

The tumf/mcp-shell-server MCP server exposes controlled local command execution through the Model Context Protocol. It launches allowlisted programs as argv arrays, supports stdin, contained redirection, pipelines, timeouts, output caps, and structured results. Use it when an MCP client needs access to selected operating-system commands, but run it inside an external OS boundary for untrusted inputs because it is not a sandbox.

Use cases

  • Run approved filesystem inspection commands
  • Pass generated input to local command-line tools
  • Collect stdout and stderr from allowlisted programs
  • Execute bounded repository or workspace utilities

Key features

  • Allowlisted argv-based command execution
  • Stdin and validated pipeline support
  • Contained file redirection
  • Timeout and output-size limits
  • Minimal child environment
  • Structured audit logging

Tools1

What MCP Shell Server lets your agent do. Expand a tool for its parameters.

Verified live~177 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 1d ago

Recent health check succeeded.

18/19 checks healthy over the last 78d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 5d ago via OSV.dev · mcp-shell-server (PyPI)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars201Stargazers on the source repository.
Last commit7d agoMost recent push to the default branch.
Tools exposed1Callable tools this server registers over MCP.
Directory activity5 viewsConfig copies, upvotes, and views on AllMCPs.

How MCP Shell Server works

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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about MCP Shell Server

tumf/mcp-shell-server is an MCP server that connects an MCP client to selected local operating-system commands. Its main tool, shell_execute, runs allowlisted programs with argv arguments, optional stdin, bounded timeouts, capped output, controlled redirection, and structured results including stdout, stderr, exit status, and execution time.

Install it with pip install mcp-shell-server, or run the published package with uvx mcp-shell-server.

Set ALLOW_COMMANDS to a comma-separated list such as ls,cat,echo. ALLOWED_COMMANDS is an alias, and ALLOW_PATTERNS can define full-match regular expressions for command names. These settings do not describe shell command strings or unrestricted argument policies.

No, it is not a sandbox. Allowlisted programs retain the server process's OS identity, filesystem and network access, credentials, and ability to start child processes. Use an external container, VM, jail, or OS policy when inputs or reachable files may be untrusted.

Related MCP servers

All in Coding Agents All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewMCP Shell Server AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/tumf-mcp-shell-server?style=directory)](https://allmcps.com/mcp/tumf-mcp-shell-server)
HTML Embed
<a href="https://allmcps.com/mcp/tumf-mcp-shell-server"><img src="https://allmcps.com/api/badge/tumf-mcp-shell-server?style=directory" alt="MCP Shell Server on AllMCPs" /></a>