Tumf MCP Shell Server

🚀 MCP Shell Server

A secure command execution server implementing the Model Context Protocol (MCP). This server allows remote execution of shell commands on a whitelist and supports passing input via stdin.

🚀 Quick Start

The MCP Shell Server is a secure command execution server that implements the Model Context Protocol (MCP). It allows for the remote execution of whitelisted shell commands and supports passing input via stdin.

✨ Features

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

📦 Installation

Install the Package

pip install mcp-shell-server

💻 Usage Examples

Configure the MCP Client in Claude.app

Release Version

code ~/Library/Application\ 支持/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\ 支持/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"
      }
    }
  }
}

Start 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 environment variable ALLOW_COMMANDS (or its alias ALLOWED_COMMANDS) specifies the commands allowed to execute. Commands are separated by commas and can contain spaces.

Supported ALLOW_COMMANDS formats:

• ls
• cat
• echo

Example Usage

Install Dependencies

pip install mcp-shell-server

Start the Server

mcp-shell-server start --port 8000

Send a Request

curl -X POST http://localhost:8000/execute \
  -H "Content-Type: application/json" \
  -d '{"command": "ls", "args": ["-a"]}'

🔧 Technical Details

Security Measures

• All command executions are performed in a sandbox.
• Dangerous operations (such as modifying the file system) are prohibited.
• Resource usage is restricted.

Requirements

• Python 3.11 or higher
• mcp >= 1.1.0

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.