Python Code Sandbox MCP

🚀 Python Code Sandbox MCP Server

A Python server implementing the Model Context Protocol (MCP) to run arbitrary Python in ephemeral Docker containers with on-the-fly pip dependency installation.

🚀 Quick Start

Usage with Claude Desktop

Add the following configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "python-sandbox": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-e", "SANDBOX_MEMORY_LIMIT=1g",
        "-e", "SANDBOX_CPU_LIMIT=0.5",
        "aixiaoke/python-code-sandbox-mcp"
      ]
    }
  }
}

Manual Execution (Docker)

docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e SANDBOX_MEMORY_LIMIT=1g \
  aixiaoke/python-code-sandbox-mcp stdio

Local Development (Without Docker Packaging)

If you want to run the server directly from source code (for development or debugging), follow these steps:

Prerequisites:

• Python 3.10+
• uv package manager (install: curl -LsSf https://astral.sh/uv/install.sh | sh or pip install uv)
• Docker (still required for running sandbox containers)

Note for Windows users: Docker Desktop with WSL2 backend is recommended. Ensure "Use the WSL 2 based engine" is enabled in Docker settings.

# 1. Clone the repository
git clone https://github.com/li-xiu-qi/python-code-sandbox-mcp.git
cd python-code-sandbox-mcp

# 2. Install dependencies
uv sync --extra dev

# 3. Run the server
uv run python -m python_code_sandbox_mcp.server

For Claude Desktop local development:

{
  "mcpServers": {
    "python-sandbox": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/python-code-sandbox-mcp",
        "python-code-sandbox"
      ]
    }
  }
}

✨ Features

• File Persistence (Smart Default): Files are automatically persisted to the host filesystem by default.
• Isolated Execution: Runs Python code in ephemeral Docker containers (python:3.11-slim by default).
• One-Shot Execution: Run scripts in a disposable container and retrieve results instantly.
• Session-Based Execution: Keep a container alive for complex, multi-step tasks.
• Dependency Management: Automatically installs pip packages from PyPI.
• Security First: Controlled CPU/Memory limits and non-root execution inside containers.
• File Retrieval: Automatically captures generated images (plots) and files.

📦 Installation

Docker must be installed and running on your machine.

Tip: Pre-pull the base image to avoid delays during first execution:

docker pull python:3.11-slim

💻 Usage Examples

run_python_ephemeral (Recommended)

Run a one-off Python script in a brand-new disposable container.

Inputs:

• code (string, required): Python source to execute.
• dependencies (array of strings, optional): Pip packages to install (e.g., ["pandas", "matplotlib"]).

Behavior:

1. Creates a fresh container.
2. Installs specified dependencies.
3. Executes the script and captures stdout/stderr.
4. Returns generated files (images as image, others as resource).
5. Tears down the container automatically.

sandbox_initialize / run_python

Start a persistent sandbox and run multiple scripts in the same environment.

Test Prompts

Once connected, try these prompts to verify:

1. Hello World: Create and run a Python script with print("Hello MCP")
2. Data Visualization: Install matplotlib and create a sine wave plot saved as 'sine.png'

📚 Documentation

• Usage Guide - Installation, configuration, and usage
• API Reference - Complete tool documentation
• Execution Modes - Ephemeral vs Session mode explained
• Examples - Practical code examples with MCP client
• Persistence - File persistence and storage options
• Architecture - System design
• Security - Security guidelines
• Troubleshooting - Common issues and solutions

Chinese Documentation

• 使用指南 - 安装、配置和使用说明
• API 参考 - 完整工具文档
• 执行模式 - 临时模式与会话模式详解
• 使用示例 - 实用代码示例

🔧 Technical Details

The server supports configuration via environment variables or a .env file. Key options include:

File Persistence (New)

By default, files created in the sandbox are persisted to the host filesystem:

• Windows: %TEMP%/python-sandbox-mcp/files/
• macOS/Linux: /tmp/python-sandbox-mcp/files/

You can customize this behavior:

• SANDBOX_FILES_DIR: Set a custom directory for file persistence (e.g., /home/user/my-sandbox-files)
• SANDBOX_FILES_DIR="": Set to empty string to disable persistence (files exist only in container)

Other Options

• PIP_CACHE_PATH: (Recommended) Absolute path on your host for persistent pip caching.
• SANDBOX_MEMORY_LIMIT: Maximum memory per container (default: 2g).
• SANDBOX_CPU_LIMIT: CPU limit per container (default: 0.5).
• ENABLE_PIP_CACHE: Set to false to disable caching.

See the Usage Guide for a full list of variables.

📄 License

MIT