Pandora's Shell

Pandora's Shell

⚠️ 重要安全警告：此 MCP 服务赋予 AI 助手在你的系统上不受限制地执行终端命令的能力。仅在虚拟机（VM）或可随时重建的开发系统等受控环境中使用。

关于

一个 MCP 服务，可让 AI 助手在你的系统上执行终端命令。由于它提供不受限制的访问权限，务必负责任地使用此软件，并充分了解其中涉及的安全风险。

注意：此服务兼容所有支持 Model Context Protocol（MCP）的 AI 助手。所提供的配置和设置说明专为 Claude Desktop 编写，该应用全面支持所有 MCP 功能。

功能

• 以完整系统访问权限执行任意 shell 命令
• 捕获命令输出（stdout/stderr）
• 设置工作目录
• 处理命令超时

API

工具

• execute_command
  • 执行任意 shell 命令并返回其输出
  • 输入：
    • command（字符串）：要执行的命令
    • directory（字符串，可选）：工作目录
  • 返回：
    • 命令退出代码
    • 标准输出
    • 标准错误
  • 功能：
    • 5 分钟超时
    • 支持工作目录
    • 错误处理

安装

前置条件

• Claude Desktop，并拥有有效的 Claude Pro/Enterprise 订阅
  • 下载地址：Claude AI
• Python 3.10 或更高版本
• Git
• uv（包管理所需）

Windows 安装

1. 安装前置条件：

   选项 A - 使用 winget（如果你的系统支持）：

   winget install python git
   

   选项 B - 手动安装（推荐）：

   • 从 python.org 下载并安装 Python
   • 从 git-scm.com 下载并安装 Git

2. 安装 uv：

   以管理员身份打开命令提示符（cmd.exe）并运行：

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

   如果遇到问题，可能需要重启终端或计算机才能使更改生效。

3. 克隆并设置项目：

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

   然后创建虚拟环境。按顺序尝试以下命令，直到其中一条生效：

   python -m venv venv
   

   如果不行，请尝试：

   python3 -m venv venv
   

   然后激活环境：

   venv\Scripts\activate
   

4. 安装依赖项：

   uv pip install mcp
   pip install -e .
   

注意：如果你从 python.org 安装了 Python，通常应使用 python。如果你通过 winget 或 Microsoft Store 安装，可能需要使用 python3。如果其中一个命令无效，请尝试另一个。

macOS 安装

1. 安装前置条件：

   brew install python git uv
   

2. 克隆并设置项目：

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

3. 安装依赖项：

   uv pip install mcp
   pip install -e .
   

配置

Windows

找到正确的配置目录 - 按顺序尝试以下路径：

1. %APPDATA%\Claude\（通常为 C:\Users\[YourUsername]\AppData\Roaming\Claude\）
2. %LOCALAPPDATA%\AnthropicClaude\（通常为 C:\Users\[YourUsername]\AppData\Local\AnthropicClaude\）

在正确的目录中创建或编辑 claude_desktop_config.json：

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

Windows 重要说明：

• 路径中使用正斜杠（/），不要使用反斜杠（\）
• 将 [YourUsername] 替换为你的实际 Windows 用户名
• 文件名必须为 claude_desktop_config.json
• 如果两个可能的配置位置都存在，请逐一尝试，直到成功

macOS

创建或编辑 ~/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"
      }
    }
  }
}

macOS 重要说明：

• 将 [YourUsername] 替换为你的实际用户名
• 如果愿意，可以使用 $HOME 代替 /Users/[YourUsername]
• 文件名必须为 claude_desktop_config.json
• command 路径应指向虚拟环境中的 Python 解释器（venv/bin/python），而不是系统 Python

配置完成后

1. 完全重启 Claude Desktop（退出应用，而不只是关闭窗口）。
2. 点击 🔌 图标，确认服务器显示在“已安装的 MCP 服务器”列表中。
3. 如果服务器未显示，请检查 Claude 的日志：
   • Windows：%APPDATA%\Claude\Logs\mcp*.log 或 %LOCALAPPDATA%\AnthropicClaude\Logs\mcp*.log
   • macOS：~/Library/Logs/Claude/mcp*.log

安全注意事项

此服务器会以你的用户权限执行命令。请采取以下预防措施：

• 仅在虚拟机或可随时丢弃的开发环境中使用。
• 切勿在生产系统或含有敏感数据的设备上使用。
• 如有需要，可考虑实施命令限制。
• 监控系统访问和活动。
• 备份重要数据。

免责声明：开发者不对因使用本软件而导致的任何损害或损失负责。使用风险由你自行承担。

故障排除

如果遇到问题：

1. 检查日志：

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

2. 验证安装：

   • 确保已正确安装 uv，且其位于 PATH 中。
   • 检查是否已安装 mcp 包：pip show mcp。
   • 确认 Python 版本为 3.10 或更高版本。

3. 配置问题：

   • 仔细检查 claude_desktop_config.json 中的所有路径。
   • 确认 JSON 语法有效。
   • 确保路径分隔符与操作系统相匹配。
   • 确认配置文件位于正确的位置。

4. 环境问题：

   • 如果使用虚拟环境，请确保已激活 virtualenv。
   • 确认 PYTHONPATH 设置正确。
   • 检查文件权限。

5. 手动测试服务器：

   # First, 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. 连接问题：

   • 如果出现“无法连接到 MCP 服务器”错误，请确保配置文件中使用的是虚拟环境的 Python 解释器。
   • 对于 macOS：使用 /path/to/cloned/Pandoras-Shell/venv/bin/python
   • 对于 Windows：使用 C:/path/to/cloned/Pandoras-Shell/venv/Scripts/python.exe

测试

完成设置后，在 Claude Desktop 中尝试以下命令：

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

或

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