Shell Command Executor MCP Server

Overview

Shell Command Executor is a secure MCP server that allows AI assistants to execute shell commands on your system in a controlled manner. It provides a safe interface for running commands with comprehensive security features to prevent unauthorized access or potentially harmful operations.

Installation

You can install the Shell Command Executor in several ways:

Using pip

pip install mcp-shell-server

Using Smithery (Recommended)

For an automated installation with Claude Desktop:

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

Configuration

To configure the Shell Command Executor, you need to specify which commands are allowed to be executed. This is done through the ALLOW_COMMANDS (or its alias ALLOWED_COMMANDS) environment variable.

Claude Desktop Configuration

Edit your Claude Desktop configuration file:

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

Add the following configuration:

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

Command Whitelist Format

The ALLOW_COMMANDS variable accepts a comma-separated list of commands:

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

Security Features

The Shell Command Executor 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
4. Timeout Control: Set maximum execution time for commands to prevent resource exhaustion

Usage Examples

The AI assistant can use the Shell Command Executor to run various commands:

1. Basic command execution:

   • List files in a directory
   • Search for text in files
   • Check system information

2. Input processing:

   • Process text through commands like grep or wc
   • Filter and transform data

3. File operations:

   • Read file contents
   • Find files matching patterns

Advanced Configuration

For local development or custom setups, you can configure the server with additional options:

{
  "mcpServers": {
    "shell": {
      "command": "uv",
      "args": [
        "--directory",
        ".",
        "run",
        "mcp-shell-server"
      ],
      "env": {
        "ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find",
        "TIMEOUT": "30"  // Default timeout in seconds
      }
    }
  }
}

Docker Deployment

The repository includes a Dockerfile for containerized deployment. This can be useful for running the server in isolated environments or cloud deployments.