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

• Multi-Language Support: Run Python, Go, and Node.js code in isolated Docker containers
• TypeScript Support: Built-in support for TypeScript and JSX/TSX files
• Dependency Management: Automatic handling of project dependencies (pip, go mod, npm)
• Flexible Execution: Custom entrypoints for both single-file code and full projects
• Background Mode: Run long-running services in the background
• Real-time Output: Capture and stream container logs in real-time

🚀 Installation

Prerequisites

• Docker installed and running
  • Install Docker for Linux
  • Install Docker Desktop for macOS
  • Install Docker Desktop for Windows

Quick Install

Unix-like Systems (Linux, macOS)

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

Example output:

Downloading latest release...
Installing to /home/user/.local/share/code-sandbox-mcp/code-sandbox-mcp...
Adding to Claude Desktop configuration...
Added code-sandbox-mcp to /home/user/.config/Claude/claude_desktop_config.json
Installation complete!
You can now use code-sandbox-mcp with Claude Desktop or other AI applications.

Windows

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

The installer will:

1. Check for Docker installation
2. Download the appropriate binary for your system
3. Create Claude Desktop configuration

Manual Installation

1. Download the latest release for your platform from the releases page
2. Place the binary in a directory in your PATH
3. Make it executable (Unix-like systems only):

   chmod +x code-sandbox-mcp
   

🛠️ Available Tools

run_code

Executes code snippets in an isolated Docker container.

Parameters:

• code (string, required): The code to run
• language (enum, required): Programming language to use
  • Supported values: python, go, nodejs
• entrypoint (string[], required): Command to run the code
  • Examples:
    • Python: ["python", "-c"]
    • Node.js: ["node", "-e"]
    • Go: ["go", "run"]

Returns:

• Text content containing the execution output (stdout + stderr)

Features:

• Automatic dependency detection and installation
  • Python: Detects imports and installs via pip
  • Node.js: Detects require/import statements and installs via npm
  • Go: Detects imports and installs via go get
• Automatic language-specific Docker image selection
• TypeScript/JSX support with appropriate flags
• Special handling for Go (code written to temporary file)
• Real-time output streaming

run_project

Executes a project directory in a containerized environment.

Parameters:

• project_dir (string, required): Directory containing the project to run
• language (enum, required): Programming language to use
  • Supported values: python, go, nodejs
• entrypoint (string[], required): Command to run the project
  • Examples:
    • Python: ["python", "main.py"]
    • Node.js: ["node", "index.js"]
    • Go: ["go", "run", "."]
• background (boolean, optional): Whether to run in background mode

Returns:

• For foreground processes: Text content containing execution output
• For background processes: Container ID and initial logs

Features:

• Automatic dependency detection and installation
• Volume mounting of project directory
• Background process support for long-running services
• Language-specific configuration handling
• Real-time log streaming

🔧 Configuration

Claude Desktop

The installer automatically creates the configuration file. If you need to manually configure it:

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

For other AI applications that support MCP servers, configure them to use the code-sandbox-mcp binary as their code execution backend.

🔧 Technical Details

Supported Languages

| Language | File Extensions | Docker Image | |----------|----------------|--------------| | Python | .py | python:3.12-slim-bookworm | | Go | .go | golang:1.21-alpine | | Node.js | .js, .ts, .tsx, .jsx | node:23-slim |

Dependency Management

The sandbox automatically detects and installs dependencies:

• Python:

  • Detects imports like import requests, from PIL import Image
  • Handles aliased imports (e.g., PIL → pillow)
  • Filters out standard library imports
  • Supports both direct imports and __import__() calls

• Node.js:

  • Detects require() statements and ES6 imports
  • Handles scoped packages (e.g., @org/package)
  • Supports dynamic imports (import())
  • Filters out built-in Node.js modules

• Go:

  • Detects package imports in both single-line and grouped formats
  • Handles named and dot imports
  • Filters out standard library packages
  • Supports external dependencies via go get

For project execution, the following files are used:

• Python: requirements.txt, pyproject.toml, setup.py
• Go: go.mod
• Node.js: package.json

TypeScript Support

Node.js 23+ includes built-in TypeScript support:

• --experimental-strip-types: Enabled by default for .ts files
• --experimental-transform-types: Used for .tsx files

🔐 Security Features

• Isolated execution environment using Docker containers
• Resource limitations through Docker container constraints
• Separate stdout and stderr streams
• Clean container cleanup after execution
• Project files mounted read-only in containers

🛠️ Development

If you want to build the project locally or contribute to its development, see DEVELOPMENT.md.

📝 License

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