Code Sandbox MCP

You can install Code Sandbox MCP using a quick install script or via manual installation.

Prerequisites

• Docker must be installed and running on your system.

Quick Install

Linux and macOS:

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

Windows (PowerShell):

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

The installer checks for Docker, downloads the appropriate binary, and creates necessary configuration files.

Manual Installation

1. Download the latest release from the GitHub releases page.
2. Place the binary in a directory included in your PATH.
3. On Unix-like systems, make the binary executable:

chmod +x code-sandbox-mcp

To build the project locally, ensure you have Go 1.21+, Docker, and Git installed. Use the provided build.sh script to compile the binaries. The resulting binaries will be placed in the bin/ directory.

# Clone the repository
git clone https://github.com/Automata-Labs-team/code-sandbox-mcp.git
cd code-sandbox-mcp

# Build for development
./build.sh

# Build for release
./build.sh --release

# Build for release with a specific version
./build.sh --release --version v1.0.0

If the installer does not automatically configure Claude Desktop, you can manually add the code-sandbox-mcp server to your claude_desktop_config.json file. Ensure the command path points to your installed binary.

Linux Path: ~/.config/Claude/claude_desktop_config.json
macOS Path: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows Path: %APPDATA%\Claude\claude_desktop_config.json

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

The installer automatically determines the correct command and arguments for code-sandbox-mcp based on the host OS:

Windows

On Windows, the server is executed via cmd using the /c flag followed by the absolute path to the executable:

• Command: cmd
• Args: ["/c", "<ABSOLUTE_PATH_TO_EXECUTABLE>"]

macOS and Linux

On non-Windows systems, the server is executed directly using its absolute path:

• Command: <ABSOLUTE_PATH_TO_EXECUTABLE>
• Args: []

The sandbox_initialize tool creates a new isolated compute environment using a Docker container. This tool returns a container_id which is required for all subsequent interactions with that specific sandbox.

Parameters:

• image (string, optional): The Docker image to use as the base environment. Defaults to 'python:3.12-slim-bookworm'.

sandbox_initialize(image='python:3.12-slim-bookworm')

The sandbox_stop tool gracefully stops a running container and removes it along with its associated volumes. It uses a 10-second timeout for the graceful shutdown.

Parameters:

• container_id (string, required): The ID of the container to stop and remove.

The sandbox_exec tool allows you to run shell commands within the containerized environment.

Parameters:

• container_id (string, required): The ID returned from sandbox_initialize.
• commands (array, required): A list of command strings to execute.

Example usage:

{
  "container_id": "your-container-id",
  "commands": ["apt-get update", "pip install numpy", "python script.py"]
}

sandbox_exec(container_id="id", commands=["pip install numpy", "python script.py"])

The project implements the MCP (Machine Code Protocol) server interface. The following core functions are used to manage the server and execution:

• NewServer: Creates a new MCP server instance.
• RegisterTool: Registers new tool endpoints.
• runInDocker: Executes single-file code in a Docker container.
• runProjectInDocker: Runs project directories in containers.

Once a sandbox is initialized, you can populate it with files using the following tools:

• copy_project: Copies an entire local directory to the sandboxed filesystem.
  • container_id (string, required)
  • local_src_dir (string, required)
  • dest_dir (string, optional)
• copy_file: Copies a single local file to the sandbox.
  • container_id (string, required)
  • local_src_file (string, required)
  • dest_path (string, optional)
• write_file: Writes specific content directly to a file in the sandbox.
  • container_id (string, required)
  • file_name (string, required)
  • file_contents (string, required)
  • dest_dir (string, optional, defaults to ${WORKDIR})

You can access the real-time or historical logs of a running container using the dynamic resource path. This returns all container logs as a single text/plain resource.

Resource Path Pattern: containers://{id}/logs

Replace {id} with the actual container_id of your sandbox.

containers://<container_id>/logs

The build.sh script supports the following flags to control the build process:

| Option | Description |
|--------|-------------|
| `--release` | Build in release mode with version information |
| `--version <ver>` | Specify a version number (e.g., v1.0.0) |

The InitializeEnvironment tool creates a new Docker container to serve as a sandboxed execution environment for code.

When calling this tool, you can optionally specify a Docker image. If no image is provided, the tool defaults to python:3.12-slim-bookworm.

Upon successful initialization, the tool returns the container_id of the running container, which can then be used by other tools to execute code within that specific environment.

{
  "name": "initialize_environment",
  "arguments": {
    "image": "python:3.12-slim-bookworm"
  }
}