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:


git clone <your-repo-url>
cd sandbox_server

Create and activate a virtual environment with uv:


uv venv
source .venv/bin/activate  # On Unix/MacOS
# Or on Windows:
# .venv\Scripts\activate

Install dependencies:


uv pip install .

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:


{
    "mcpServers": {
        "sandbox": {
            "command": "uv",
            "args": [
                "--directory",
                "/absolute/path/to/sandbox_server",
                "run",
                "sandbox_server.py"
            ],
            "env": {
                "PYTHONPATH": "/absolute/path/to/sandbox_server"
            }
        }
    }
}

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:


Could you create a Python container and write a simple hello world program?

Run code in different languages:


Could you create a C program that calculates the fibonacci sequence and run it?

Install packages and use them:


Could you create a Python script that uses numpy to generate and plot some random data?

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:


Could you create a persistent Python container with numpy and pandas installed?

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:


Could you save the current container state as an image named 'my-ds-env:v1'?

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:


Could you create a new container using the my-ds-env:v1 image?

Generating Dockerfiles

To make your environment fully reproducible, you can generate a Dockerfile:


Could you export a Dockerfile that recreates this environment?

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:


Create a persistent Python container for data science work

Install needed packages and set up the environment:


Install numpy, pandas, and scikit-learn in the container

Test your setup:


Create and run a test script to verify the environment

Save the state:


Save this container as 'ds-workspace:v1'

Export a Dockerfile:


Generate a Dockerfile for this environment

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


sandbox_server/
├── sandbox_server.py     # Main server implementation
├── pyproject.toml        # Project configuration
└── README.md            # This file

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