Pandora's Shell

⚠️ 重要安全警告: 此 MCP 服务器授予 AI 助手对您系统执行终端命令的无限制能力。仅在受控环境（如虚拟机 (VM)）或您可以重建的开发系统中使用。

关于

一个 MCP 服务器，使 AI 助手能够执行您系统上的终端命令。由于这提供了不受限制的访问权限，因此负责任地使用此软件并充分了解所涉及的安全风险至关重要。

注意: 此服务器与任何支持模型上下文协议 (MCP) 的 AI 助手兼容。提供的配置和设置说明专门为 Claude Desktop 定制，它为所有 MCP 功能提供全面支持。

功能

• 执行任何具有完整系统访问权限的 shell 命令
• 捕获命令输出 (stdout/stderr)
• 设置工作目录
• 处理命令超时

API

工具

• execute_command
  • 执行任何 shell 命令并返回其输出
  • 输入:
    • command (string): 要执行的命令
    • directory (string, 可选): 工作目录
  • 返回:
    • 命令退出代码
    • 标准输出
    • 标准错误
  • 功能:
    • 5 分钟超时
    • 工作目录支持
    • 错误处理

安装

前提条件

• 具有有效 Claude Pro/Enterprise 订阅的 Claude Desktop
  • 从以下位置下载：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

安全注意事项

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

• 仅在 VM 或一次性开发环境中使用。
• 切勿在生产系统或具有敏感数据的机器上使用。
• 如果需要，考虑实施命令限制。
• 监控系统访问和活动。
• 保留重要数据的备份。

免责声明: 开发人员不对因使用此软件而造成的任何损害或损失负责。 使用风险自负。

故障排除

如果遇到问题：

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. 手动测试服务器：

   # 首先，确保您位于 Pandoras-Shell 目录中：
   cd /path/to/cloned/Pandoras-Shell
   
   # 对于 macOS：
   ./venv/bin/python src/pandoras_shell/executor.py
   
   # 对于 Windows：
   .\venv\Scripts\python.exe src\pandoras_shell\executor.py
   
   # 执行器将显示为挂起且没有输出 - 这是正常的。
   # 它正在等待来自 Claude Desktop 的连接。
   # 使用 Ctrl+C 停止它。
   

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 中尝试以下命令：

你能运行 'pwd' 并告诉我我们在哪个目录吗？

或者

你能列出我的主目录中的文件吗？ 其中哪些大于 200 MB？