Pandora's Shell MCP 服务器使用说明

项目简介

Pandora's Shell 是一个 MCP (Model Context Protocol) 服务器，旨在为 AI 助手提供执行系统终端命令的能力。通过 Pandora's Shell，AI 助手可以与您的操作系统进行交互，执行各种命令，并获取命令输出，从而实现更强大的自动化和系统管理功能。

重要安全警告： 此 MCP 服务器赋予 AI 助手在您的系统上执行终端命令的不受限制的能力。仅在受控环境（如虚拟机或您可以重建的开发系统）中使用。 请务必仔细阅读安全注意事项并负责任地使用本软件。

主要功能点

执行任意 Shell 命令: 允许 AI 助手执行任何可在您的系统终端中运行的命令。
捕获命令输出: 返回命令的标准输出 (stdout) 和标准错误 (stderr)，使 AI 助手能够理解命令执行结果。
设置工作目录: 支持在指定的目录下执行命令，方便进行文件操作和路径管理。
命令超时处理: 为命令执行设置超时时间（5分钟），防止长时间运行的命令阻塞系统。

安装步骤

前提条件：

Claude Desktop (需 Claude Pro/Enterprise 订阅) - 从 Claude AI 下载安装
Python 3.10 或更高版本
Git
uv (包管理工具，安装步骤中会介绍)

Windows 安装步骤：

安装必备软件：
- 推荐方式 (手动安装):
  - 从 python.org 下载并安装 Python 3.10 或更高版本。
  - 从 git-scm.com 下载并安装 Git。
- 可选方式 (使用 winget，如果您的系统支持): 打开 PowerShell 运行 'winget install python git'

安装 uv： 以管理员身份打开命令提示符 (cmd.exe) 并运行命令：

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

克隆项目并设置： 打开命令提示符，执行以下命令：

git clone https://github.com/MCP-Mirror/Zelaron_Pandoras-Shell.git
cd Zelaron_Pandoras-Shell
python -m venv venv  # 创建虚拟环境
venv\Scripts\activate # 激活虚拟环境

安装依赖： 在激活的虚拟环境中运行：

uv pip install mcp
pip install -e .

macOS 安装步骤：

安装必备软件： 打开终端并运行命令：

brew install python git uv

克隆项目并设置： 在终端中执行以下命令：

git clone https://github.com/MCP-Mirror/Zelaron_Pandoras-Shell.git
cd Zelaron_Pandoras-Shell
python3 -m venv venv # 创建虚拟环境
source venv/bin/activate # 激活虚拟环境

安装依赖： 在激活的虚拟环境中运行：

uv pip install mcp
pip install -e .

服务器配置

要将 Pandora's Shell 配置为 Claude Desktop 的 MCP 服务器，您需要编辑 Claude Desktop 的配置文件 'claude_desktop_config.json'。

Windows 配置：

找到 Claude Desktop 的配置目录 (尝试以下路径，通常是其中一个)：
- '%APPDATA%\Claude' (例如 'C:\Users[您的用户名]\AppData\Roaming\Claude')
- '%LOCALAPPDATA%\AnthropicClaude' (例如 'C:\Users[您的用户名]\AppData\Local\AnthropicClaude')
在配置目录中创建或编辑 'claude_desktop_config.json' 文件，并添加以下 JSON 配置。请根据您的实际项目路径修改 'command'、'args' 和 'env' 中的路径。
```
{
  "mcpServers": {
    "pandoras-shell": {
      "command": "Python 解释器路径",
      "args": [
        "executor.py 脚本路径"
      ],
      "env": {
        "PYTHONPATH": "项目 src 目录路径"
      }
    }
  }
}
```
配置参数说明 (无需用户填写，仅供理解):
- '"command"': 指向您克隆的 Pandora's Shell 项目中虚拟环境内的 Python 解释器可执行文件的路径。例如 'C:/path/to/cloned/Pandoras-Shell/venv/Scripts/python.exe' (注意使用正斜杠 '/')。
- '"args"': 一个字符串数组，包含启动服务器脚本的参数。这里指向 'executor.py' 脚本的路径。例如 '["C:/path/to/cloned/Pandoras-Shell/src/pandoras_shell/executor.py"]' (注意使用正斜杠 '/')。
- '"env"': 一个环境变量字典。'PYTHONPATH' 需要设置为指向项目 'src' 目录的路径，例如 '"PYTHONPATH": "C:/path/to/cloned/Pandoras-Shell/src"' (注意使用正斜杠 '/')。

macOS 配置：

创建或编辑 '~/Library/Application Support/Claude/claude_desktop_config.json' 文件。
添加以下 JSON 配置。 同样，请根据您的实际项目路径修改 'command'、'args' 和 'env' 中的路径。
```
{
  "mcpServers": {
    "pandoras-shell": {
      "command": "Python 解释器路径",
      "args": [
        "executor.py 脚本路径"
      ],
      "env": {
        "PYTHONPATH": "项目 src 目录路径"
      }
    }
  }
}
```
配置参数说明 (无需用户填写，仅供理解):
- '"command"': 指向您克隆的 Pandora's Shell 项目中虚拟环境内的 Python 解释器可执行文件的路径。例如 '/path/to/cloned/Pandoras-Shell/venv/bin/python'。
- '"args"': 一个字符串数组，包含启动服务器脚本的参数。这里指向 'executor.py' 脚本的路径。例如 '["/path/to/cloned/Pandoras-Shell/src/pandoras_shell/executor.py"]'。
- '"env"': 一个环境变量字典。'PYTHONPATH' 需要设置为指向项目 'src' 目录的路径，例如 '"PYTHONPATH": "/path/to/cloned/Pandoras-Shell/src"'。

配置完成后：

重启 Claude Desktop (完全退出并重新打开)。
点击 Claude Desktop 界面上的 🔌 图标，检查 "已安装的 MCP 服务器" 列表中是否出现 "pandoras-shell"。
如果未出现，请查看 Claude Desktop 的日志文件以排查问题：
- Windows: '%APPDATA%\Claude\Logs\mcp*.log' 或 '%LOCALAPPDATA%\AnthropicClaude\Logs\mcp*.log'
- macOS: '~/Library/Logs/Claude/mcp*.log'

基本使用方法

配置并启动 Pandora's Shell 后，您可以在 Claude Desktop 中使用以下指令来让 AI 助手执行系统命令：

查看当前工作目录：

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

列出用户主目录下的文件并查找大于 200MB 的文件：

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

您可以根据需要，让 AI 助手执行各种终端命令，例如文件操作、系统信息查询、程序启动等。

安全提示： 请务必谨慎使用 Pandora's Shell，并仅在安全可控的环境中使用。

关键词