Docker Code Sandbox

🚀 MCP Docker Sandbox Interpreter

A Docker-based secure code execution environment for the Model Context Protocol (MCP).

🚀 Quick Start

This project offers a secure sandbox for executing code via the Model Context Protocol (MCP). It enables AI assistants to run code without direct access to the host system, as all code is executed within isolated Docker containers.

graph LR
    A[Claude/Cursor] -->|Send code| B[MCP Server]
    B -->|Execute code| C[Docker Sandbox]
    C -->|Return result| A

✨ Features

• Secure Execution: Code runs within isolated Docker containers with strict security restrictions.
• Multi-language Support: Currently supports Python, and other languages can be easily extended.
• Resource Limitation: CPU and memory limits are set to prevent abuse.
• MCP Integration: Fully compatible with the Model Context Protocol.
• Automatic Setup: Handles container creation, dependency installation, and cleanup.

📦 Installation

Requirements

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

Steps

1. Clone this repository:

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

2. Create and activate a virtual environment:

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

3. Install dependencies:

   pip install -r requirements.txt
   

💻 Usage Examples

Start the MCP Server

Run the following commands to start the server:

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

# Run the server
uv run mcp dev main.py

Connect with AI Assistants

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

Cursor

In Cursor, add the following content 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

Create a new Docker container for code execution.

Parameters:
- image: The Docker image to use (default: "alpine:latest")

execute_code

Run code in the initialized sandbox.

Parameters:
- code: The code string to execute
- language: The language of the code (default: "python")

clean_container

Clean up containers that are no longer needed.

No parameters

📚 Documentation

How It Works

1. Initialization Phase:

   • Create and start a Docker container.
   • Configure the basic development environment.

2. Execution Phase:

   • Send the code to the container.
   • Run the code in the specified language environment.
   • Return the execution result or error information.

3. Cleanup Phase:

   • Regularly check and clean up containers that are no longer needed to free up resources.

Security Considerations

• Isolation: All code runs in independent Docker containers to prevent malicious code from affecting the host system.
• Limitation: Set upper limits on CPU and memory usage to prevent resource abuse.
• Monitoring: Support real-time monitoring and termination of processes with abnormal behavior.

Development Information

• This project is built on the Docker SDK for Python, providing powerful container management capabilities.
• It is fully compatible with the Model Context Protocol and can be integrated with other MCP tools and services.