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

• Secure Command Execution: Only whitelisted commands can be executed
• Standard Input Support: Pass input to commands via stdin
• Comprehensive Output: Returns stdout, stderr, exit status, and execution time
• Shell Operator Safety: Validates commands after shell operators (; , &&, ||, |)
• Timeout Control: Set maximum execution time for commands

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

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

Request Format

# Basic command execution
{
    "command": ["ls", "-l", "/tmp"]
}

# Command with stdin input
{
    "command": ["cat"],
    "stdin": "Hello, World!"
}

# Command with timeout
{
    "command": ["long-running-process"],
    "timeout": 30  # Maximum execution time in seconds
}

# Command with working directory and timeout
{
    "command": ["grep", "-r", "pattern"],
    "directory": "/path/to/search",
    "timeout": 60
}

Response Format

Successful response:

{
    "stdout": "command output",
    "stderr": "",
    "status": 0,
    "execution_time": 0.123
}

Error response:

{
    "error": "Command not allowed: rm",
    "status": 1,
    "stdout": "",
    "stderr": "Command not allowed: rm",
    "execution_time": 0
}

Security

The server implements several security measures:

1. Command Whitelisting: Only explicitly allowed commands can be executed
2. Shell Operator Validation: Commands after shell operators (;, &&, ||, |) are also validated against the whitelist
3. No Shell Injection: Commands are executed directly without shell interpretation

Development

Setting up Development Environment

1. Clone the repository

git clone https://github.com/yourusername/mcp-shell-server.git
cd mcp-shell-server

2. Install dependencies including test requirements

pip install -e ".[test]"

Running Tests

pytest

API Reference

Request Arguments

Field	Type	Required	Description
command	string[]	Yes	Command and its arguments as array elements

            | stdin     | string     | No       | Input to be passed to the command            |

| directory | string | No | Working directory for command execution | | timeout | integer | No | Maximum execution time in seconds |

Response Fields

Field	Type	Description
stdout	string	Standard output from the command
stderr	string	Standard error output from the command
status	integer	Exit status code
execution_time	float	Time taken to execute (in seconds)
error	string	Error message (only present if failed)

Requirements

• Python 3.11 or higher
• mcp>=1.1.0

License

MIT License - See LICENSE file for details