📌Overview

Purpose: Pandora's Shell is designed to enable AI assistants to execute terminal commands on a system, providing a powerful interface while highlighting the importance of security.

Overview: This MCP server allows AI assistants, particularly Claude Desktop, to have unrestricted access for executing shell commands. This capability requires a high level of caution due to significant security implications, making it suitable only for controlled environments like VMs or development systems.

Key Features:

• Execute Any Shell Command: Allows comprehensive control over the system by executing any shell command directly, which provides flexibility in automation and task execution.

• Capture Command Output: Easily captures and returns both standard output and error messages from executed commands, facilitating debugging and process monitoring.

• Set Working Directory: Users can define the working directory for command execution, ensuring commands run in the intended context.

• Handle Command Timeouts: Offers built-in support for command execution timeouts, preventing long-running commands from hanging the system and maintaining responsiveness.

---

Pandora's Shell

⚠️ IMPORTANT SECURITY WARNING: This MCP server grants AI assistants unrestricted ability to execute terminal commands on your system. Only use in controlled environments like virtual machines (VMs) or development systems you can afford to rebuild.

About

An MCP server that empowers AI assistants to execute terminal commands on your system. Due to the unrestricted access this provides, it's crucial to use this software responsibly and be fully aware of the security risks involved.

Note: This server is compatible with any AI assistant that supports the Model Context Protocol (MCP). The provided configuration and setup instructions are specifically tailored for Claude Desktop, which offers comprehensive support for all MCP features.

Features

• Execute any shell command with full system access
• Capture command output (stdout/stderr)
• Set working directory
• Handle command timeouts

API

Tools

• execute_command
  • Execute any shell command and return its output
  • Inputs:
    • command (string): Command to execute
    • directory (string, optional): Working directory
  • Returns:
    • Command exit code
    • Standard output
    • Standard error
  • Features:
    • 5-minute timeout
    • Working directory support
    • Error handling

Installation

Prerequisites

• Claude Desktop with an active Claude Pro/Enterprise subscription
  • Download from: https://claude.ai/download
• Python 3.10 or higher
• Git
• uv (required for package management)

Windows Installation

1. Install Prerequisites:

   Option A - Using winget (if available):

   winget install python git
   

   Option B - Manual installation (recommended):

   • Download and install Python from python.org
   • Download and install Git from git-scm.com

2. Install uv:

   Open Command Prompt (cmd.exe) as administrator and run:

   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   

   If you encounter any issues, restart your terminal or computer.

3. Clone and set up the project:

   git clone https://github.com/Zelaron/Pandoras-Shell.git
   cd Pandoras-Shell
   

   Create a virtual environment. Try these commands in order until one works:

   python -m venv venv
   

   If that doesn't work:

   python3 -m venv venv
   

   Then activate the environment:

   venv\Scripts\activate
   

4. Install dependencies:

   uv pip install mcp
   pip install -e .
   

Note: Depending on your Python installation, you may need to use python or python3.

macOS Installation

1. Install Prerequisites:

   brew install python git uv
   

2. Clone and set up the project:

   git clone https://github.com/Zelaron/Pandoras-Shell.git
   cd Pandoras-Shell
   python3 -m venv venv
   source venv/bin/activate
   

3. Install dependencies:

   uv pip install mcp
   pip install -e .
   

Configuration

Windows

Locate the correct configuration directory by checking these paths in order:

1. %APPDATA%\Claude\ (e.g., C:\Users\[YourUsername]\AppData\Roaming\Claude\)
2. %LOCALAPPDATA%\AnthropicClaude\ (e.g., C:\Users\[YourUsername]\AppData\Local\AnthropicClaude\)

Create or edit claude_desktop_config.json in the correct directory:

{
  "mcpServers": {
    "pandoras-shell": {
      "command": "C:/path/to/cloned/Pandoras-Shell/venv/Scripts/python.exe",
      "args": [
        "C:/path/to/cloned/Pandoras-Shell/src/pandoras_shell/executor.py"
      ],
      "env": {
        "PYTHONPATH": "C:/path/to/cloned/Pandoras-Shell/src"
      }
    }
  }
}

Important Notes for Windows:

• Use forward slashes (/) in paths
• Replace [YourUsername] with your actual Windows username
• File must be named exactly claude_desktop_config.json
• If both config locations exist, try each until successful

macOS

Create or edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pandoras-shell": {
      "command": "/path/to/cloned/Pandoras-Shell/venv/bin/python",
      "args": [
        "/path/to/cloned/Pandoras-Shell/src/pandoras_shell/executor.py"
      ],
      "env": {
        "PYTHONPATH": "/path/to/cloned/Pandoras-Shell/src"
      }
    }
  }
}

Important Notes for macOS:

• Replace [YourUsername] with your actual username
• You can use $HOME instead of /Users/[YourUsername] if preferred
• File must be named exactly claude_desktop_config.json
• The command path should point to the Python interpreter inside your virtual environment (venv/bin/python), not the system Python

After Configuration

1. Restart Claude Desktop completely (quit/exit, not just close).
2. Click the 🔌 icon to verify the server appears in the "Installed MCP Servers" list.
3. If the server doesn't appear, check Claude's logs:
   • Windows: %APPDATA%\Claude\Logs\mcp*.log or %LOCALAPPDATA%\AnthropicClaude\Logs\mcp*.log
   • macOS: ~/Library/Logs/Claude/mcp*.log

Security Considerations

This server executes commands with your user privileges. Take these precautions:

• Use only in VMs or disposable development environments.
• Never use on production systems or machines with sensitive data.
• Consider implementing command restrictions if needed.
• Monitor system access and activity.
• Keep backups of important data.

Disclaimer: The developers are not responsible for any damages or losses resulting from the use of this software. Use it at your own risk.

Troubleshooting

1. Check logs:

   • Windows: %APPDATA%\Claude\Logs\mcp*.log or %LOCALAPPDATA%\AnthropicClaude\Logs\mcp*.log
   • macOS: ~/Library/Logs/Claude/mcp*.log

2. Verify installation:

   • Ensure uv is installed and in your PATH.
   • Check that mcp package is installed: pip show mcp.
   • Verify Python version is 3.10 or higher.

3. Configuration issues:

   • Double-check all paths in claude_desktop_config.json.
   • Verify JSON syntax is valid.
   • Ensure proper path separators for your OS.
   • Confirm config file is in the correct location.

4. Environment issues:

   • Make sure the virtual environment is activated if using one.
   • Verify PYTHONPATH is set correctly.
   • Check file permissions.

5. Test server manually:

   # Make sure you're in the Pandoras-Shell directory:
   cd /path/to/cloned/Pandoras-Shell
   
   # For macOS:
   ./venv/bin/python src/pandoras_shell/executor.py
   
   # For Windows:
   .\venv\Scripts\python.exe src\pandoras_shell\executor.py
   
   # The executor will appear to hang with no output - this is normal.
   # It's waiting for connections from Claude Desktop.
   # Use Ctrl+C to stop it.
   

6. Connection issues:

   • Ensure you're using the virtual environment's Python interpreter in your config file.
   • For macOS: Use /path/to/cloned/Pandoras-Shell/venv/bin/python
   • For Windows: Use C:/path/to/cloned/Pandoras-Shell/venv/Scripts/python.exe

Testing

After setup, try these commands in Claude Desktop:

Can you run 'pwd' and tell me what directory we're in?

or

Can you list the files in my home directory? Which of them are larger than 200 MB?