Code Sandbox MCP

A FastMCP code sandbox server with containerized code execution capabilities.

Features

• Set up containers dynamically to execute Python and Bash code in isolated containers
• Exposes a single execute_code tool.

Quick Start

Prerequisites

• You must have Docker installed

Configuration

Adjust the .env file:

CODE_SANDBOX_PATH=<absolute_path> # REQUIRED: set this to an absolute path where the code sandbox will be mounted
MCP_SERVER_PORT=8008              # OPTIONAL: Set this to the port on your host machine where the mcp server should be accessible
PORT_MIN=8061                     # OPTIONAL: Set this to the start of the searchable port range for new execution containers
PORT_MAX=8070                     # OPTIONAL: Set this to the end of the searchable port range for new execution containers
KEEP_ALIVE=false                  # OPTIONAL: Set this to 'true' if code execution containers should remain alive on mcp server shutdown.

*Note: A new connection to the mcp server will create a subdirectory in the CODE_SANDBOX_PATH named after the connections kernel_id parameter

Launching the MCP server

Launch the mcp server

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

# Launch the server; this builds the image for the code environment containers first and then launches the mcp server
docker compose --profile build-only up --build && docker compose up -d

Connecting to the Server

To connect to this server with an MCP client, you can pass this json config in your client:

    mcp_config = {
        "mcpServers": {
            "CodeSandbox": {
                "url": "http://127.0.0.1:8008"
            }
        }
    }

PocketAgent Connection

If you are using PocketAgent you can pass a context_id query param to pre-assign a kernel_id to any agent:

agent = SimpleAgent(
    agent_config=config,
    mcp_config=mcp_config
    mcp_server_query_params={
        "context_id": "1111"
    }
)

Using Custom Docker Images

You can customize the execution environment by editing the container service Dockerfile at ./container_service/Dockerfile. Note the comments throughout this file, indicating which parts must be maintained.