MCP Shell Server

🚀 MCP Shell Server

A secure command execution server that implements the Model Context Protocol (MCP). This server allows remote execution of approved shell commands and supports passing input via stdin.

🚀 Quick Start

Prerequisites

• Python 3.11 or higher
• mcp>=1.1.0

Installation

pip install mcp-shell-server

Starting the Server

ALLOW_COMMANDS="ls,cat,echo" uvx mcp-shell-server
# Or use the alias
ALLOWED_COMMANDS="ls ,echo, cat" uvx mcp-shell-server

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

Valid formats for ALLOW_COMMANDS:

ALLOW_COMMANDS="ls,cat,echo"          # Basic format
ALLOWED_COMMANDS="ls ,echo, cat"      # Format with spaces

Request Example

{
  "id": "string",
  "method": "shell",
  "params": {
    "command": "string"
  }
}

Security Precautions

• All command executions are carried out in a controlled environment.
• Dangerous system calls and file operations are prohibited.

✨ Features

• Secure Command Execution: Only approved commands are allowed to execute.
• Standard Input Support: Pass input to commands via stdin.
• Comprehensive Output: Return stdout, stderr, exit status, and execution time.
• Shell Operator Security: Validate commands after shell operators (; , &&, ||, |).
• Timeout Control: Set the maximum execution time for commands.

📦 Configuration of the MCP Client in Claude.app

Released 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"
      }
    }
  }
}

📄 License

This project is under the MIT License - see the LICENSE file for details.