Sandbox MCP

🚀 Sandbox MCP Introduction

Sandbox MCP is a Model Context Protocol (MCP) server that allows Large Language Models (LLMs, i.e., MCP hosts/clients) to run code in securely isolated Docker containers.

Although LLMs excel at generating code, most cannot execute the code they generate. This may lead you to run untested code directly on your machine, which could cause serious and unexpected consequences.

By enabling LLMs to test code securely, such issues can be prevented, and it helps you generate more accurate code more quickly.

Sandbox MCP provides an easy-to-use execution environment for LLMs, which anyone can create and configure locally through a simple, AI-native MCP server.

• Inspired by Codapi. Some sandboxes are the same as Codapi sandboxes.

✨ Features

Demo

This demo shows how Sandbox MCP can be used with Claude Desktop:

If the GIF is not clear, try watching the video demo.mp4.

📦 Installation

Download the Binary

You can download the binary file suitable for your operating system (e.g., Darwin) and processor architecture (e.g., arm64) from the Releases page (e.g., sandbox-mcp_Darwin_arm64.tar.gz).

Install with Go

Prerequisites:

• Go 1.24 or higher

go install github.com/pottekkat/sandbox-mcp/cmd/sandbox-mcp@latest

Get the path of the sandbox-mcp binary:

which sandbox-mcp

Build from Source Code

See the Development section.

💻 Usage Examples

Initialization

Before using sandbox-mcp with an LLM, you need to initialize its configuration:

# Create the configuration directory $XDG_CONFIG_HOME/sandbox-mcp and pull the default sandboxes from GitHub
sandbox-mcp --pull

# Build the Docker images for the sandboxes
sandbox-mcp --build

⚠️ Important Note

Make sure Docker is installed and running.

Use with MCP Host/Client

Add the following content to your claude_desktop_config.json (for Claude Desktop) or mcp.json (for Cursor IDE):

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

⚠️ Important Note

Replace path/to/sandbox-mcp with the actual path of the sandbox-mcp binary.

Available Sandboxes

shell

Run shell commands in a Linux environment with strict security and network restrictions.

python

Run Python code in an environment pre-installed with specific libraries.

⚠️ Important Note

Custom Sandboxes

You can create your own sandboxes to support more languages or tools, such as Go, Java, or SQL.

network_tools

Securely execute network-related tasks in a restricted network environment.

🔧 Technical Details

Development

# Fork the repository and switch to the project directory
git clone https://github.com/pottekkat/sandbox-mcp.git && cd sandbox-mcp

# Install dependencies
npm install

# Build the Docker image (located in the `docker/` directory)
docker build -t sandbox-mcp .

# Run tests
npm test

Sandbox MCP provides a reliable method for securely executing code generated by LLMs, which is valuable for both developers and ordinary users.