python-mcp-沙箱

Name: python-mcp-沙箱
Author: JohanLi233

作者：JohanLi23330 星标更新：2025-11-22

安装使用来源：spider==github.com

项目介绍

MCP 沙箱

随时尝试 mcp 沙箱

中文文档 | English

示例

Python MCP 沙箱是一个交互式 Python 代码执行工具，允许用户和大型语言模型（LLMs）在隔离的 Docker 容器中安全地执行 Python 代码并安装包。

Viby

Viby 与 mcp 沙箱配合使用

功能

🐳 Docker 隔离：在隔离的 Docker 容器中安全运行 Python 代码
📦 包管理：支持自定义 PyPI 镜像，轻松安装和管理 Python 包
📊 文件生成：支持生成文件并通过网络链接访问
🔐 认证：多用户环境下的可选 API 密钥认证
🎨 Web 界面：内置 Web 界面用于管理沙箱和查看执行结果
🌐 SSE 支持：通过 Server-Sent Events 实现实时通信，以集成 MCP

安装

# 克隆仓库
git clone https://github.com/JohanLi233/python-mcp-sandbox.git
cd python-mcp-sandbox

# 使用 uv 安装依赖
uv venv
uv sync

# 启动服务
uv run main.py

默认的 SSE 端点是 http://127.0.0.1:8181/sse，可以通过 MCP Inspector 或任何支持 SSE 连接的客户端进行交互。

配置

可以在 config.toml 中自定义服务器配置：

主机：默认为 127.0.0.1（仅限本地）
端口：默认为 8181
PyPI 镜像：配置首选的 Python 包索引镜像

要允许外部访问，请将配置文件中的主机更改为 0.0.0.0。

可用工具

create_sandbox：创建一个新的 Python Docker 沙箱，并返回其 ID 以便后续代码执行和包安装
list_sandboxes：列出所有现有的沙箱（Docker 容器），以便复用
execute_python_code：在指定的 Docker 沙箱中执行 Python 代码
install_package_in_sandbox：在指定的 Docker 沙箱中安装 Python 包
check_package_installation_status：检查 Docker 沙箱中是否已安装或安装状态
execute_terminal_command：在指定的 Docker 沙箱中执行终端命令。参数：sandbox_id（字符串），command（字符串）。返回 stdout，stderr，exit_code。
upload_file_to_sandbox：上传本地文件到指定的 Docker 沙箱。参数：sandbox_id（字符串），local_file_path（字符串），dest_path（字符串，可选，默认：/app/results）。

项目结构

python-mcp-sandbox/
├── main.py                    # 应用入口点
├── requirements.txt           # 项目依赖
├── Dockerfile                 # Python 容器的 Docker 配置
├── results/                   # 生成文件的目录
├── mcp_sandbox/               # 主包目录
│   ├── __init__.py
│   ├── models.py              # Pydantic 模型
│   ├── api/                   # API 相关组件
│   │   ├── __init__.py
│   │   └── routes.py          # API 路由定义
│   ├── core/                  # 核心功能
│   │   ├── __init__.py
│   │   ├── docker_manager.py  # Docker 容器管理
│   │   └── mcp_tools.py       # MCP 工具
│   └── utils/                 # 工具
│       ├── __init__.py
│       ├── config.py          # 配置常量
│       ├── file_manager.py    # 文件管理
│       └── task_manager.py    # 周期性任务管理
└── README.md                  # 项目文档

示例提示

我为您配置了一个 Python 代码执行沙箱。您可以按照以下步骤运行 Python 代码：

1. 首先，使用 "list_sandboxes" 工具查看所有现有的沙箱（Docker 容器）。
   - 如果存在可用的沙箱，可以复用其 sandbox_id，无需创建新的。
   - 如果需要新的沙箱，使用 "create_sandbox" 工具。
   - 每个沙箱都是一个独立的 Python 环境，后续操作都需要提供 sandbox_id。

2. 如果需要安装包，使用 "install_package_in_sandbox" 工具
   - 参数：sandbox_id 和 package_name（例如，numpy, pandas）
   - 开始异步安装并立即返回状态

3. 安装包后，可以使用 "check_package_installation_status" 工具检查安装状态
   - 参数：sandbox_id 和 package_name（要检查的包名）
   - 如果包仍在安装中，需要再次使用此工具检查

4. 使用 "execute_python_code" 工具运行您的代码
   - 参数：sandbox_id 和 code（Python 代码）
   - 返回输出、错误以及生成文件的链接
   - 所有生成的文件都存储在沙箱内，文件链接是直接的 HTTP 链接，可在浏览器中内联查看

示例工作流程：
- 使用 list_sandboxes 查看可用的沙箱，如果没有可用的沙箱，使用 create_sandbox 创建新的 → 获取 sandbox_id
- 使用 install_package_in_sandbox 安装必要的包（如 pandas, matplotlib），参数为 sandbox_id
- 使用 check_package_installation_status 验证包的安装，参数为相同的 sandbox_id
- 使用 execute_python_code 运行您的代码，参数为 sandbox_id

代码执行在一个安全的沙箱中进行。生成的文件（图像、CSV 等）将以直接的 HTTP 链接形式提供，可以在浏览器中内联查看。

请不要在 Python 代码中使用 plt.show()。对于可视化：
- 使用 plt.savefig() 保存图像文件而不是 plt.show()
- 对于数据，使用 df.to_csv() 或 df.to_excel() 方法保存为文件
- 所有保存的文件都会自动出现在结果中作为 HTTP 链接，可以直接打开或嵌入。

MCP 示例配置

以下是 Claude Desktop 的示例配置：

{
  "mcpServers": {
    "mcpSandbox": {
      "command": "npx",
      "args": ["-y", "supergateway", "--sse",  "http://127..0.1:8181/sse"]
    }
  }
}

如果启用了认证，包含 API 密钥：

{
  "mcpServers": {
    "mcpSandbox": {
      "command": "npx",
      "args": ["-y", "supergateway", "--sse",  "http://127.0.0.1:8181/sse?api_key=<YOUR_API_KEY>"]
    }
  }
}

MCP 在线演示示例配置

{
  "mcpServers": {
    "mcpSandbox": {
      "command": "npx",
      "args": ["-y", "supergateway", "--sse",  "http://115.190.87.78/sse?api_key=<API_KEY>"]
    }
  }
}

根据您的环境需要修改 serverUrl。