Docker Sandbox

🚀 Sandbox MCP Server

A MCP server that provides an isolated Docker environment for code execution. This server allows you to:

• Create containers using any Docker image.
• Write and execute code in multiple programming languages.
• Install packages and set up development environments.
• Run commands in isolated containers.

🚀 Quick Start

Prerequisites

• Python 3.9 or higher.
• Docker installed and running.
• uv package manager (recommended).
• Docker MCP server (recommended).

📦 Installation

1. Clone this repository:

git clone <your-repo-url>
cd sandbox_server

2. Create and activate a virtual environment with uv:

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

3. Install dependencies:

uv pip install .

Integration into Claude Desktop

1. Open the configuration file of Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json%

2. Add the configuration of the sandbox server:

{
    "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 of your project.

3. Restart Claude Desktop.

💻 Usage Examples

Basic Usage

Once connected to Claude Desktop, you can:

1. Create a Python container:

Can you create a Python container and write a simple "Hello, world" program?

2. Run code in different languages:

Can you create a C program to calculate the Fibonacci sequence and run it?

3. Install packages and use them:

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

Saving and Reproducing the Experimental Environment

The server provides several ways to save and reproduce your development environment:

Create a Persistent Container

When creating a container, you can make it persistent:

Can you create a persistent Python container and install numpy and pandas?

This will create a container that:

• Continues to run after Claude Desktop is closed.
• Can be accessed directly via Docker.
• Retains all installed packages and files.

The server will provide instructions on how to:

• Access the container directly using docker exec.
• Stop and start the container.
• Delete it when it is no longer needed.

Save the Container State

After setting up the environment, you can save it as a Docker image:

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

This will:

1. Create a new Docker image that includes all your:
   • Installed packages.
   • Created files.
   • Configuration changes.
2. Provide instructions on how to reuse the environment.

Then you can share this image or create a new container based on it:

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

Export a Dockerfile

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

Can you export a Dockerfile to recreate this environment?

The generated Dockerfile includes:

• Base image specifications.
• Created files.
• Templates for additional setup steps.

You can use this Dockerfile to:

1. Share your environment settings with other users.
2. Version control your environment.
3. Modify and customize the build process.
4. Deploy to different systems.

Recommended Tools

1. create_container_environment: Create a new Docker container with a specified image.
2. create_file_in_container: Create a file in the container.
3. execute_command_in_container: Run a command in the container.
4. save_container_state: Save the container state to a persistent container.
5. export_dockerfile: Export a Dockerfile to create a persistent environment.
6. exit_container: Close the container to clean up the environment.