Overview

MCP Shell Server allows AI assistants to execute shell commands on your system through a secure interface that implements the Model Context Protocol (MCP). This enables AI models to interact with your file system and run commands while maintaining strict security controls.

Installation

You can install MCP Shell Server using pip:

pip install mcp-shell-server

For development purposes, you can install it with test dependencies:

pip install -e ".[test]"

Configuration

Claude Desktop Configuration

To use MCP Shell Server with Claude Desktop, you need to update your Claude configuration file:

1. Open your Claude Desktop configuration file:

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

2. Add the shell server configuration:

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

Security Configuration

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

Valid formats:

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

Usage

Starting the Server

You can start the server directly with the allowed commands specified:

ALLOW_COMMANDS="ls,cat,echo" uvx mcp-shell-server

Request Format

The server accepts JSON requests with the following structure:

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

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

# Command with timeout
{
    "command": ["grep", "-r", "pattern"],
    "timeout": 30
}

# Command with working directory
{
    "command": ["find", ".", "-name", "*.py"],
    "directory": "/path/to/search",
    "timeout": 60
}

Response Format

Successful responses include stdout, stderr, exit status, and execution time:

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

Error responses include an error message:

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

Security Features

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

Request Parameters

| Parameter | 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