MCP Shell Server

A secure server for executing shell commands that implements the Model Context Protocol (MCP). This server allows remote execution of authorized shell commands with support for input via stdin.

Features

Secure Command Execution : Only authorized commands can be executed
Standard Input Support : Passes input to commands via stdin
Comprehensive Output : Returns stdout, stderr, exit code and execution time
Security with Shell Operators : Validates commands after shell operators (;, &&, ||, |)
Timeout Control : Sets maximum execution time for commands

Configuring the MCP client 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

Settings

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

Use

Starting the Server

ALLOW_COMMANDS="ls,cat,echo" uvx mcp-shell-server
# Ou usando o alias
ALLOWED_COMMANDS="ls,cat,echo" uvx mcp-shell-server

The ALLOW_COMMANDS environment variable (or its alias ALLOWED_COMMANDS ) specifies which commands can 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"          # Formato básico
ALLOWED_COMMANDS="ls ,echo, cat"      # Com espaços (usando alias)
ALLOW_COMMANDS="ls,  cat  , echo"     # Múltiplos espaços

Request Format

# Execução básica de comando
{
    "command": ["ls", "-l", "/tmp"]
}

# Comando com entrada stdin
{
    "command": ["cat"],
    "stdin": "Hello, World!"
}

# Comando com timeout
{
    "command": ["long-running-process"],
    "timeout": 30  # Tempo máximo de execução em segundos
}

# Comando com diretório de trabalho e timeout
{
    "command": ["grep", "-r", "pattern"],
    "directory": "/path/to/search",
    "timeout": 60
}

Response Format

Successful response:

{
    "stdout": "saída do comando",
    "stderr": "",
    "status": 0,
    "execution_time": 0.123
}

Error response:

{
    "error": "Comando não permitido: rm",
    "status": 1,
    "stdout": "",
    "stderr": "Comando não permitido: rm",
    "execution_time": 0
}

Security

The server implements several security measures:

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

Development

Setting Up the Development Environment

Clone the repository

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

Install dependencies including test requirements

pip install -e ".[test]"

Running Tests

pytest

API Reference

Request Arguments

Field	Type	Mandatory	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 executing the command
timeout	whole	No	Maximum execution time in seconds

Response Fields

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

Requirements

Python 3.11 or higher
mcp>=1.1.0

License

MIT License - See LICENSE file for details