📌Overview

Purpose: To provide a secure shell command execution server that adheres to the Model Context Protocol (MCP).

Overview: The MCP Shell Server allows for the remote execution of predefined shell commands safely and efficiently, enabling applications to interact with the command line while enforcing strict security policies.

Key Features:

Secure Command Execution: Only whitelisted commands can be executed, preventing unauthorized access to the system.
Standard Input Support: Facilitates the passing of input to commands via stdin, enhancing the versatility of command execution.
Comprehensive Output: Returns standard output, standard error, exit status, and execution time for commands, enabling effective monitoring and debugging.
Shell Operator Safety: Validates commands post-shell operators to ensure only safe and allowed commands are processed.
Timeout Control: Provides the ability to set a maximum execution time for commands, enhancing control over resource utilization.

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

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

Valid formats:

ALLOW_COMMANDS="ls,cat,echo"
ALLOWED_COMMANDS="ls ,echo, cat"
ALLOW_COMMANDS="ls,  cat  , echo"

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
}

# 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

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

Development

Setting up 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	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 (present if failed)

Requirements

Python 3.11 or higher
mcp>=1.1.0

License

MIT License - See LICENSE file for details