MCP Shell Server

A secure shell command execution server implementing the Model Context Protocol (MCP). This server allows remote execution of whitelisted shell commands with support for stdin input.

Features

• Argv-based Command Execution: Allowed commands run via subprocess argv without shell-string interpretation
• Standard Input Support: Pass input to commands via stdin
• Comprehensive Output: Returns stdout, stderr, exit status, and execution time
• Safe Pipeline Support: Pipelines preserve and validate argv segments instead of invoking a shell
• Execution Limits: Server-side default timeout, maximum timeout, and output byte caps are enforced
• Contained Redirection: <, >, and >> targets must stay inside the requested working directory
• Minimal Child Environment: Child processes receive a small allowlisted environment instead of inheriting all server secrets
• Structured Audit Logging: Success, rejection, timeout, output-cap, and process-error outcomes are logged with redaction

MCP client setting in your Claude.app

Published version

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "shell": {
      "command": "uvx",
      "args": [
        "mcp-shell-server"
      ],
      "env": {
        "ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find"
      }
    },
  }
}

Local version

Configuration

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "shell": {
      "command": "uv",
      "args": [
        "--directory",
        ".",
        "run",
        "mcp-shell-server"
      ],
      "env": {
        "ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find"
      }
    },
  }
}

Installation

Installing via Smithery

To install Shell Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install mcp-shell-server --client claude

Manual Installation

pip install mcp-shell-server

Usage

Starting the Server

ALLOW_COMMANDS="ls,cat,echo" uvx mcp-shell-server
# Or using the alias
ALLOWED_COMMANDS="ls,cat,echo" uvx mcp-shell-server

The ALLOW_COMMANDS (or its alias ALLOWED_COMMANDS ) environment variable specifies which commands are allowed to be executed. Commands can be separated by commas with optional spaces around them.

Valid formats for ALLOW_COMMANDS or ALLOWED_COMMANDS:

ALLOW_COMMANDS="ls,cat,echo"          # Basic format
ALLOWED_COMMANDS="ls ,echo, cat"      # With spaces (using alias)
ALLOW_COMMANDS="ls,  cat  , echo"     # Multiple spaces

ALLOW_PATTERNS can be used for comma-separated regular expressions that match command names. Each pattern is applied with full-match semantics, so ALLOW_PATTERNS="ls" allows only the command name ls and does not allow lsof or ls -la. Patterns and command names containing whitespace or shell metacharacters are rejected; do not use ALLOW_PATTERNS to describe shell command strings or argument-level policies.

ALLOW_PATTERNS="python[0-9.]*,node"    # Command-name patterns only