MCP Sandbox

MCP Sandbox

欢迎试用 mcp sandbox

中文文档 | 英文

演示

Python MCP Sandbox 是一款交互式 Python 代码执行工具，允许用户和大模型在隔离的 Docker 容器中安全地执行 Python 代码和安装软件包。

Viby

Viby 可与 mcp sandbox 配合使用

功能

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

安装

# Clone the repository
git clone https://github.com/JohanLi233/python-mcp-sandbox.git
cd python-mcp-sandbox

# Install dependencies using uv
uv venv
uv sync

# Start the server
uv run main.py

默认的 SSE 端点为 http://127.0.0.1:8181/sse，你可以通过 SSE 使用 MCP Inspector 与其交互，也可以使用任何支持 SSE 连接的客户端。

配置

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

• 主机：默认为 127.0.0.1（仅限本地主机）
• 端口：默认为 8181
• PyPI 镜像：配置你偏好的 Python 软件包索引镜像

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

可用工具

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

项目结构

python-mcp-sandbox/
├── main.py                    # Application entry point
├── requirements.txt           # Project dependencies
├── Dockerfile                 # Docker configuration for Python containers
├── results/                   # Directory for generated files
├── mcp_sandbox/               # Main package directory
│   ├── __init__.py
│   ├── models.py              # Pydantic models
│   ├── api/                   # API related components
│   │   ├── __init__.py
│   │   └── routes.py          # API route definitions
│   ├── core/                  # Core functionality
│   │   ├── __init__.py
│   │   ├── docker_manager.py  # Docker container management
│   │   └── mcp_tools.py       # MCP tools
│   └── utils/                 # Utilities
│       ├── __init__.py
│       ├── config.py          # Configuration constants
│       ├── file_manager.py    # File management
│       └── task_manager.py    # Periodic task management
└── README.md                  # Project documentation

提示词示例

I've configured a Python code execution sandbox for you. You can run Python code using the following steps:

1. First, use the "list_sandboxes" tool to view all existing sandboxes (Docker containers).
   - You can reuse an existing sandbox_id if a sandbox exists, do not create a new one.
   - If you need a new sandbox, use the "create_sandbox" tool.
   - Each sandbox is an isolated Python environment, and the sandbox_id is required for all subsequent operations.

2. If you need to install packages, use the "install_package_in_sandbox" tool
   - Parameters: sandbox_id and package_name (e.g., numpy, pandas)
   - This starts asynchronous installation and returns immediately with status

3. After installing packages, you can check their installation status using the "check_package_installation_status" tool
   - Parameters: sandbox_id and package_name (name of the package to check)
   - If the package is still installing, you need to check again using this tool

4. Use the "execute_python_code" tool to run your code
   - Parameters: sandbox_id and code (Python code)
   - Returns output, errors and links to any generated files
   - All generated files are stored inside the sandbox, and file_links are direct HTTP links for inline viewing

Example workflow:
- Use list_sandboxes to check for available sandboxes, if no available sandboxes, use create_sandbox to create a new one → Get sandbox_id
- Use install_package_in_sandbox to install necessary packages (like pandas, matplotlib), with the sandbox_id parameter
- Use check_package_installation_status to verify package installation, with the same sandbox_id parameter
- Use execute_python_code to run your code, with the sandbox_id parameter

Code execution happens in a secure sandbox. Generated files (images, CSVs, etc.) will be provided as direct HTTP links, which can viewed inline in the browser.

Remember not to use plt.show() in your Python code. For visualizations:
- Save figures to files using plt.savefig() instead of plt.show()
- For data, use methods like df.to_csv() or df.to_excel() to save as files
- All saved files will automatically appear as HTTP links in the results, which you can open or embed directly.

MCP 配置示例

以下是 Claude Desktop 的配置示例：

{
  "mcpServers": {
    "mcpSandbox": {
      "command": "npx",
      "args": ["-y", "supergateway", "--sse",  "http://127.0.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。