Docker Sandbox MCP server

This MCP server provides isolated Docker environments for code execution, allowing you to create containers with any Docker image, write and execute code in multiple languages, install packages, and run commands in isolated environments.

Prerequisites

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

Installation

Setting Up the Server

1. Clone the 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 .
   

Integrating 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:

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

   Be sure to replace /absolute/path/to/sandbox_server with the actual path to your project directory.

3. Restart Claude Desktop

Using the Sandbox Server

Basic Usage

Once connected to Claude Desktop, you can interact with the sandbox server:

1. Create a Python container:

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

2. Run code in different languages:

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

3. Install packages and use them:

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

Working with Persistent Environments

Creating Persistent Containers

Make a container that persists after Claude Desktop closes:

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

This creates a container that:

• Remains running after closing Claude Desktop
• Can be accessed directly through Docker
• Preserves all installed packages and files

Saving Container State

Save your environment as a Docker image:

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

This will:

1. Create a new Docker image preserving all:
   • Installed packages
   • Created files
   • Configuration changes
2. Provide instructions for reusing the environment

To use a saved image:

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

Generating Dockerfiles

Create a reproducible environment definition:

Could you export a Dockerfile that recreates this environment?

The generated Dockerfile includes:

• Base image specification
• Created files
• Template for additional setup steps

Recommended Workflow

For reproducible development environments:

1. Create a persistent container:

   Create a persistent Python container for data science work
   

2. Install needed packages:

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

3. Test your setup:

   Create and run a test script to verify the environment
   

4. Save the state:

   Save this container as 'ds-workspace:v1'
   

5. Export a Dockerfile:

   Generate a Dockerfile for this environment
   

Security Features

• All code executes in isolated Docker containers
• Containers are automatically removed after use
• File systems are isolated between containers
• Host system access is restricted

Available Commands

The server provides these 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 as a persistent container
• export_dockerfile: Exports a Dockerfile to create a persistent environment
• exit_container: Closes a container to cleanup environment when finished

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "sandbox" '{"command":"uv","args":["--directory","/absolute/path/to/sandbox_server","run","sandbox_server.py"],"env":{"PYTHONPATH":"/absolute/path/to/sandbox_server"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect