Sandbox MCP Server

🚀 Sandbox MCP Server

A MCP server that provides an isolated Docker environment for code execution. This server allows you to:

• Create containers using any Docker image.
• Write and execute code in multiple programming languages.
• Install packages and set up development environments.
• Run commands in isolated containers.

🚀 Quick Start

Prerequisites

• Python 3.9 or higher.
• Installed and running Docker.
• uv package manager (recommended).
• Docker MCP Server (recommended).

📦 Installation

1. Clone this repository:

git clone <your-repo-url>
cd sandbox_server

2. Create and activate a virtual environment with uv:

uv venv
source .venv/bin/activate  # On Unix/MacOS
# Or on Windows:
# .venv\Scripts\activate

3. Install dependencies:

uv pip install .

Integration with Claude Desktop

1. Open the configuration file of Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json%

2. Add the configuration of the sandbox server:

{
    "mcpServers": {
        "sandbox": {
            "command": "uv",
            "args": [
                "--directory",
                "/absolute/path/to/sandbox_server",
                "run",
                "sandbox_server.py"
            ],
            "env": {
                "PYTHONPATH": "/absolute/path/to/sandbox_server"
            }
        }
    }
}

Replace /absolute/path/to/sandbox_server with the actual path of the project directory.

3. Restart Claude Desktop.

💻 Usage Examples

Basic Usage

Once connected to Claude Desktop, you can:

1. Create a Python container:

Can you create a Python container and write a simple "Hello, World" program?

2. Run code in different languages:

Can you create a C program to calculate the Fibonacci sequence and run it?

3. Install packages and use them:

Can you create a Python script that uses numpy to generate and plot some random data?

Saving and Reproducing the Experimental Environment

The server provides multiple ways to save and reproduce your development environment:

Create a Persistent Container

When creating a container, you can set it to be persistent:

Can you create a persistent Python container with numpy and pandas installed?

This will create a container that:

• Keeps running after Claude Desktop is closed.
• Can be directly accessed via Docker.
• Retains all installed packages and files. The server will provide the following instructions:
• Access the container directly using docker exec.
• Stop and start the container.
• Delete it when it is no longer needed.

Save the Container State

Can you save the state of the container to a persistent container?

Export the Dockerfile

Can you export a Dockerfile to create a persistent environment?

Exit the Container

Can you close the container to clean up the environment?

⚠️ Important Note

• Ensure that you use trusted sources when running external commands.
• Avoid executing user-provided code in an untrusted environment.

🔧 Technical Details

Project Structure

[Here should be the content about project structure if there was any in the original Chinese doc, but it seems it's not provided fully in the input. So this part remains empty for now.]