MCP Docker Sandbox Interpreter

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

Overview

This project provides a secure sandbox for executing code through MCP (Model Context Protocol). It allows AI assistants to safely run code without requiring direct access to the host system, by executing all code within isolated Docker containers.

graph LR
    A[Claude/Cursor] -->|Sends Code| B[MCP Server]
    B -->|Executes Code| C[Docker Sandbox]
    C -->|Returns Results| A

Features

Secure Execution: Code runs in isolated Docker containers with strict security limitations
Multi-Language Support: Currently supports Python with easy extensibility for other languages
Resource Limitations: CPU and memory restrictions to prevent abuse
MCP Integration: Fully compatible with the Model Context Protocol
Automatic Setup: Handles container creation, dependency installation, and cleanup

Requirements

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

Installation

Clone this repository:

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 by running:

# 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

Development

Project Structure

mcp-docker-interpreter/
├── main.py          # Main implementation of MCP server and Docker sandbox
├── requirements.txt # Project dependencies
└── README.md        # This file

Adding New Language Support

To add support for a new programming language, modify the run_code method in the DockerSandbox class to handle the new language.

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

License

MIT License

Acknowledgements

This project uses the Model Context Protocol
Built with Docker SDK for Python

Docker Sandbox Interpreter