Sandbox MCP Server
An MCP server that provides isolated Docker environments for code execution. This server allows you to:
- Create containers with any Docker image
- Write and execute code in multiple programming languages
- Install packages and set up development environments
- Run commands in isolated containers
Prerequisites
- Python 3.9 or higher
- Docker installed and running
- uv package manager (recommended)
- Docker MCP server (recommended)
Installation
- Clone this repository:
- Create and activate a virtual environment with uv:
- Install dependencies:
Integration with Claude Desktop
- Open Claude Desktop's configuration file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Add the sandbox server configuration:
Replace `/absolute/path/to/sandbox_server` with the actual path to your project directory.
- Restart Claude Desktop
Usage Examples
Basic Usage
Once connected to Claude Desktop, you can:
- Create a Python container:
- Run code in different languages:
- Install packages and use them:
Saving and Reproducing Environments
The server provides several ways to save and reproduce your development environments:
Creating Persistent Containers
When creating a container, you can make it persistent:
This will create a container that:
- Stays running after Claude Desktop closes
- Can be accessed directly through Docker
- Preserves all installed packages and files
The server will provide instructions for:
- Accessing the container directly (`docker exec`)
- Stopping and starting the container
- Removing it when no longer needed
Saving Container State
After setting up your environment, you can save it as a Docker image:
This will:
- Create a new Docker image with all your: - Installed packages - Created files - Configuration changes
- Provide instructions for reusing the environment
You can then share this image or use it as a starting point for new containers:
Generating Dockerfiles
To make your environment fully reproducible, you can generate a Dockerfile:
The generated Dockerfile will include:
- Base image specification
- Created files
- Template for additional setup steps
You can use this Dockerfile to:
- Share your environment setup with others
- Version control your development environment
- Modify and customize the build process
- Deploy to different systems
Recommended Workflow
For reproducible development environments:
- Create a persistent container:
- Install needed packages and set up the environment:
- Test your setup:
- Save the state:
- Export a Dockerfile:
This gives you multiple options for recreating your environment:
- Use the saved Docker image directly
- Build from the Dockerfile with modifications
- Access the original container if needed
Security Notes
- All code executes in isolated Docker containers
- Containers are automatically removed after use
- File systems are isolated between containers
- Host system access is restricted
Project Structure
Available Tools
The server provides three main tools:
- `create_container_environment`: Creates a new Docker container with specified image
- `create_file_in_container`: Creates a file in a container
- `execute_command_in_container`: Runs commands in a container
- `save_container_state`: Saves the container state to a persistent container
- `export_dockerfile`: exports a docker file to create a persistant environment
- `exit_container`: closes a container to cleanup environment when finished