📌Overview

Purpose: To provide a secure and isolated environment for executing code within Docker containers, ensuring safety and flexibility for AI applications.

Overview: Code Sandbox MCP is a server designed to facilitate code execution in a controlled Docker environment. It leverages container technology to isolate the execution process, ensuring that applications remain secure while offering the flexibility needed to handle various coding tasks.

Key Features:

Flexible Container Management: Easily create and manage isolated environments for execution using Docker, enhancing security and resource management.
Custom Environment Support: Provide versatility by allowing any Docker image to be used as the execution environment, catering to diverse application needs.
Real-time Logging: Stream logs and command outputs in real-time, allowing for immediate monitoring and debugging of code execution processes.
Multi-Platform Support: Ensure compatibility across Linux, macOS, and Windows, broadening the accessibility of the server for different users.

Code Sandbox MCP 🐳

A secure sandbox environment for executing code within Docker containers. This MCP server provides AI applications with a safe and isolated environment for running code while maintaining security through containerization.

🌟 Features

Flexible Container Management: Create and manage isolated Docker containers for code execution
Custom Environment Support: Use any Docker image as your execution environment
File Operations: Easy file and directory transfer between host and containers
Command Execution: Run any shell commands within the containerized environment
Real-time Logging: Stream container logs and command output in real-time
Auto-Updates: Built-in update checking and automatic binary updates
Multi-Platform: Supports Linux, macOS, and Windows

🚀 Installation

Prerequisites

Docker installed and running
- Install Docker for Linux: https://docs.docker.com/engine/install/
- Install Docker Desktop for macOS: https://docs.docker.com/desktop/install/mac/
- Install Docker Desktop for Windows: https://docs.docker.com/desktop/install/windows-install/

Quick Install

Linux, macOS

curl -fsSL https://raw.githubusercontent.com/Automata-Labs-team/code-sandbox-mcp/main/install.sh | bash

Windows

# Run in PowerShell
irm https://raw.githubusercontent.com/Automata-Labs-team/code-sandbox-mcp/main/install.ps1 | iex

The installer will:

Check for Docker installation
Download the appropriate binary for your system
Create necessary configuration files

Manual Installation

Download the latest release for your platform from the releases page: https://github.com/Automata-Labs-team/code-sandbox-mcp/releases
Place the binary in a directory in your PATH
Make it executable (Unix-like systems only):
```
chmod +x code-sandbox-mcp
```

🛠️ Available Tools

`sandbox_initialize`

Initialize a new compute environment for code execution by creating a container based on the specified Docker image.

Parameters:

image (string, optional): Docker image to use as the base environment
- Default: python:3.12-slim-bookworm

Returns:

container_id for interacting with this environment

`copy_project`

Copy a directory to the sandboxed filesystem.

Parameters:

container_id (string, required)
local_src_dir (string, required): Path to a local directory
dest_dir (string, optional): Destination path in the sandbox

`write_file`

Write a file to the sandboxed filesystem.

Parameters:

container_id (string, required)
file_name (string, required)
file_contents (string, required)
dest_dir (string, optional, default: ${WORKDIR})

`sandbox_exec`

Execute commands in the sandboxed environment.

Parameters:

container_id (string, required)
commands (array, required): List of shell commands
- Example: ["apt-get update", "pip install numpy", "python script.py"]

`copy_file`

Copy a single file to the sandboxed filesystem.

Parameters:

container_id (string, required)
local_src_file (string, required)
dest_path (string, optional)

`sandbox_stop`

Stop and remove a running container sandbox.

Parameters:

container_id (string, required)

Stops the container gracefully with a 10-second timeout and removes it along with its volumes.

Container Logs Resource

Provides access to container logs.

Resource Path: containers://{id}/logs
MIME Type: text/plain
Returns all container logs from the specified container as a single text resource.

🔐 Security Features

Isolated execution environment using Docker containers
Resource limitations through Docker container constraints
Separate stdout and stderr streams

🔧 Configuration

Claude Desktop

The installer automatically creates the configuration file. To configure manually:

Linux (~/.config/Claude/claude_desktop_config.json)

{
    "mcpServers": {
        "code-sandbox-mcp": {
            "command": "/path/to/code-sandbox-mcp",
            "args": [],
            "env": {}
        }
    }
}

macOS (~/Library/Application Support/Claude/claude_desktop_config.json)

{
    "mcpServers": {
        "code-sandbox-mcp": {
            "command": "/path/to/code-sandbox-mcp",
            "args": [],
            "env": {}
        }
    }
}

Windows (%APPDATA%\Claude\claude_desktop_config.json)

{
    "mcpServers": {
        "code-sandbox-mcp": {
            "command": "C:\\path\\to\\code-sandbox-mcp.exe",
            "args": [],
            "env": {}
        }
    }
}

Other AI Applications

Configure AI applications supporting MCP servers to use the code-sandbox-mcp binary as the code execution backend.

🛠️ Development

For local building or contributing, see DEVELOPMENT.md.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.