Docker Code Sandbox MCP server

This MCP Docker Sandbox Interpreter provides a secure Docker-based code execution environment for the Model Context Protocol (MCP). It allows AI assistants to safely run code in isolated Docker containers without requiring direct access to the host system.

Requirements

• Docker (Desktop or Engine)
• Python 3.10+
• MCP SDK (pip install mcp)
• Docker Python SDK (pip install docker)

Installation

Clone the repository and set up the environment:

git clone https://github.com/yourusername/mcp-docker-interpreter.git
cd mcp-docker-interpreter

Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt

Usage

Starting the MCP Server

Start the server with the following command:

# For Colima users:
export DOCKER_HOST="unix:///Users/username/.colima/default/docker.sock"

# Run the server
uv run mcp dev main.py

Connecting to an AI Assistant

You can connect this MCP server to AI assistants that support the Model Context Protocol:

Cursor

In Cursor, add the following to your MCP settings:

{
  "mcpServers": {
    "docker-sandbox": {
      "command": "python",
      "args": ["/absolute/path/to/your/main.py"],
      "env": {
        "DOCKER_HOST": "unix:///path/to/your/docker.sock"
      }
    }
  }
}

Replace the paths with your actual file paths.

Claude Desktop

Similar to Cursor, add the configuration to Claude Desktop's MCP settings.

MCP Tools

This MCP server exposes three main tools:

• initialize_sandbox: Creates a new Docker container for code execution

  • Arguments:
    • image: The Docker image to use (default: "alpine:latest")

• execute_code: Runs code in the initialized sandbox

  • Arguments:
    • code: The code string to execute
    • language: Programming language (default: "python")

• stop_sandbox: Stops and removes the container

  • No arguments needed

How It Works

When initialize_sandbox is called, the system:

• Creates a Docker container based on Alpine Linux
• Installs Python and other dependencies
• Sets up security restrictions

When execute_code is called:

• Code is executed within the isolated container
• Standard output and errors are captured
• Results are returned to the calling application

When stop_sandbox is called:

• The container is stopped and removed
• All resources are released

Security Considerations

This sandbox implements several security measures:

• Containers have restricted CPU and memory usage
• Containers are run with minimal privileges
• Network access is disabled by default
• Containers are disposable and cleaned up after use

Troubleshooting

Common Issues

• Docker connection error:

  • Ensure Docker is running
  • Check that the DOCKER_HOST environment variable is correctly set for your Docker installation

• Container creation fails:

  • Verify you have permission to create Docker containers
  • Ensure the specified base image is accessible

• Code execution fails:

  • Check that the language runtime is properly installed in the container
  • Verify the code is valid for the specified language

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.