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)

Related MCP server: Python MCP Sandbox

Installation

1. Clone this repository:

2. Create and activate a virtual environment with uv:

3. Install dependencies:

Integration with Claude Desktop

1. Open Claude Desktop's configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the sandbox server configuration:

Replace /absolute/path/to/sandbox_server with the actual path to your project directory.

3. Restart Claude Desktop

Usage Examples

Basic Usage

Once connected to Claude Desktop, you can:

1. Create a Python container:

2. Run code in different languages:

3. 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:

1. Create a new Docker image with all your:

   • Installed packages

   • Created files

   • Configuration changes

2. 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:

1. Share your environment setup with others

2. Version control your development environment

3. Modify and customize the build process

4. Deploy to different systems

Recommended Workflow

For reproducible development environments:

1. Create a persistent container:

2. Install needed packages and set up the environment:

3. Test your setup:

4. Save the state:

5. 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:

1. create_container_environment: Creates a new Docker container with specified image

2. create_file_in_container: Creates a file in a container

3. execute_command_in_container: Runs commands in a container

4. save_container_state: Saves the container state to a persistent container

5. export_dockerfile: exports a docker file to create a persistant environment

6. exit_container: closes a container to cleanup environment when finished