MCP Sandbox is a Python-based server that lets you create and manage isolated Docker sandboxes to execute Python code securely and install Python packages inside those sandboxes. It exposes tools to create and list sandboxes, run code, install packages, check installation status, run arbitrary terminal commands, and upload files into sandboxes. The server’s web UI and Server-Sent Events (SSE) stream execution results in real-time, making it suitable for integration with MCP clients and the MCP Inspector. Start by configuring the server (host/port and PyPI mirror) and then use the available tools to manage sandboxes, execute code, and retrieve generated files via HTTP links.

Prerequisites:

• Python 3.12+ installed on the host
• Docker installed and running
• uv (Astral’s UV package manager) available in your environment

Install steps:

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

2. Install and run the server using UV:

   Create a virtual environment and synchronize dependencies

   uv venv uv sync

   Start the MCP Sandbox server (Python implementation)

   uv run main.py

3. By default, the server exposes the SSE endpoint at http://127.0.0.1:8181/sse. Configure config.toml if you need to change host/port or PyPI mirror settings.

Notes:

• Ensure Docker is running to enable sandbox containers.
• If you plan to expose the server externally, update the host in config.toml to 0.0.0.0 and adjust firewall rules accordingly.

Tips and common issues:

• SSE endpoint: The default SSE feed is http://127.0.0.1:8181/sse. Use this URL in MCP clients to receive real-time execution updates.
• Configuration: Update config.toml to set Host, Port, and PyPI Mirror. Allow external access by setting Host to 0.0.0.0.
• Authentication: You can enable API key-based authentication for multi-user environments; pass the API key via the SSE URL if enabled.
• File handling: Generated files from code execution are stored inside the sandbox and exposed via HTTP links; use plt.savefig() or df.to_csv() to produce files you can access via links.
• Sandbox lifecycle: Use create_sandbox to instantiate a new Docker sandbox and obtain a sandbox_id for subsequent operations with other tools.
• Security: Although Docker isolates execution, ensure Docker daemon permissions and network access are secured in production environments.