home / mcp / sandbox mcp server
Isolated Docker-based sandbox that lets you write, run, and manage code in containers with editable environments.
Configuration
View docs{
"mcpServers": {
"tsuchijo-sandbox-mcp": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/sandbox_server",
"run",
"sandbox_server.py"
],
"env": {
"PYTHONPATH": "/absolute/path/to/sandbox_server"
}
}
}
}You run code inside isolated Docker containers through an MCP server that exposes a sandboxed environment for writing, running, and testing code across languages. It lets you create containers from Docker images, install packages, and manage development environments without affecting your host system.
Connect to the Sandbox MCP Server using your MCP client to create and manage isolated containers. You can spin up a Python container to write and test code, run programs in other languages, install packages, and persist or export environments for reuse. All code executes inside containers that are isolated from your host, with separate file systems and restricted host access.
Prerequisites: you need Python 3.9 or higher and Docker installed and running on your machine. You also use the uv package manager to manage the MCP server locally.
# Prerequisites
python3 --version
docker --version
# Install your MCP runner (uv) and set up a local environment for the Sandbox MCP Server
# Step 1: Ensure uv is available and create a virtual environment
# Install uv if not already installed (example for macOS/Linux)
pip install uv
# Step 2: Clone the sandbox server project and enter the directory
git clone <your-repo-url>
cd sandbox_server
# Step 3: Create and activate a virtual environment with uv
uv venv
source .venv/bin/activate # On Unix/MacOS
# Or on Windows:
# .venv\Scripts\activate
# Step 4: Install dependencies for the Sandbox MCP Server
uv pip install .To connect Claude Desktop or a similar MCP client to the Sandbox MCP Server, configure the MCP server entry with the following details. This runs the server in a local stdio mode using uv and points to the sandbox server script.
{
"mcpServers": {
"sandbox": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/sandbox_server",
"run",
"sandbox_server.py"
],
"env": {
"PYTHONPATH": "/absolute/path/to/sandbox_server"
}
}
}
}All code executes in isolated Docker containers. Containers are automatically removed after use and file systems are isolated between containers. The host system access is restricted to protect your environment.
You typically have a sandbox_server directory containing the main server implementation, project configuration, and supporting docs. The server offers a set of tools to manage containers, files, and commands within those containers.
Create and run a Python container to test code, then save or export the environment as needed. You can persist containers so they stay running after the client closes, or convert your setup into a Docker image or a Dockerfile for reproducible environments.
You can save the current container state as a Docker image and export a Dockerfile to recreate the environment elsewhere. This supports sharing environments or deploying them to other systems.
The server supports creating containers with various Docker images, installing packages, and running commands in isolated containers. You can manage the lifecycle of containers, including stopping, starting, and removing them as needed.
The server provides: create_container_environment, create_file_in_container, execute_command_in_container, save_container_state, export_dockerfile, exit_container.
Creates a new Docker container with the specified image and environment setup.
Creates or writes a file inside a running container.
Executes a command inside a running container and captures output.
Saves the current container state to a persistent image for reuse.
Exports a Dockerfile that reproduces the current container environment.
Closes and cleans up the active container session.