MCP4Modal Sandbox

A powerful Model Context Protocol (MCP) server that provides seamless cloud-based sandbox management using Modal.com. This project enables LLMs and AI assistants to spawn, manage, and interact with isolated compute environments in the cloud with full GPU support.

Features

Core Sandbox Management

Launch Sandboxes: Create isolated Python environments with custom configurations
Terminate Sandboxes: Clean resource management and controlled shutdown
List Sandboxes: Monitor and track active sandbox environments
App Namespacing: Organize sandboxes within Modal app namespaces

Advanced Configuration

Python Versions: Support for multiple Python versions (default: 3.12)
Package Management: Install pip and apt packages during sandbox creation
Resource Allocation: Configure CPU cores, memory, and execution timeouts
Working Directory: Set custom working directories for sandbox environments

GPU Support

Comprehensive GPU support for machine learning and compute-intensive workloads:

T4: Entry-level GPU, ideal for inference workloads
L4: Mid-range GPU for general ML tasks
A10G: High-performance GPU for training (up to 4 GPUs)
A100-40GB/80GB: High-end GPUs for large-scale training
L40S: Latest generation GPU for ML workloads
H100: Latest generation high-end GPU
H200: Latest generation flagship GPU
B200: Latest generation enterprise GPU

File Operations

Push Files: Upload files from local filesystem to sandboxes
Pull Files: Download files from sandboxes to local filesystem
Read File Content: View file contents directly without downloading
Write File Content: Create and edit files within sandboxes
Directory Management: Create, list, and remove directories

Command Execution

Remote Execution: Run arbitrary commands in sandbox environments
Output Capture: Capture stdout, stderr, and return codes
Timeout Control: Configure execution timeouts for long-running tasks
Performance Metrics: Track execution time and resource usage

Security & Environment Management

Secrets Management: Inject environment variables and secrets
Predefined Secrets: Reference existing secrets from Modal dashboard
Volume Mounting: Attach persistent storage volumes
Isolated Environments: Complete isolation between sandbox instances

Transport Options

stdio: Direct command-line interface (default)
streamable-http: HTTP-based communication
SSE: Server-Sent Events for real-time updates

rerequisites

Python 3.12+
Modal.com account and API key
Environment variables configured (see Configuration section)

Installation

Using UV (Recommended)

# Clone the repository
git clone https://github.com/milkymap/mcp4modal_sandbox.git
cd mcp4modal_sandbox

# Install dependencies
uv sync

# Install in development mode
uv pip install -e .

Using Docker

Build the Docker Image

# Build the Docker image
docker build -t mcp4modal-sandbox f Dockerfile .

Run with stdio Transport (Default)

# Run --help to find options
docker run -it \
  -e MODAL_TOKEN_ID="your_modal_token_id" \
  -e MODAL_TOKEN_SECRET="your_modal_token_secret" \
  mcp4modal-sandbox --help

Configuration

Environment Variables

Create a .env file in the project root:

# Required: Modal.com API Configuration
MODAL_TOKEN_ID="your_modal_token_id"
MODAL_TOKEN_SECRET="your_modal_token_secret"

# Optional: HTTP Transport Configuration (only needed for streamable-http/sse transports)
MCP_HOST="0.0.0.0"  # Default: 0.0.0.0
MCP_PORT=8000       # Default: 8000

Modal.com Setup

Create an account at Modal.com
Generate API tokens from your Modal dashboard
Configure the tokens in your environment variables

Integration with Claude Desktop

Add to your Claude Desktop configuration:

uvx

{
  "mcpServers": {
    "mcp4modal-sandbox": {
        "command": "uvx",
        "args": [
          "mcp4modal-sandbox",
          "--transport", "stdio",
          "--app_name", "namespace",
          "--preloaded_secrets", "group0", // modal secret
          "--preloaded_secrets", "group1" // modal secret
          ],
        "env": {
          "MODAL_TOKEN_ID": "",
          "MODAL_TOKEN_SECRET": ""
        }
    }
  }
}

docker

{
  "mcpServers": {
    "mcp4modal-sandbox": {
        "command": "docker",
        "args": [
          "run", "--rm", "-i", "--name", "modal_sandbox",
          "-e", "MODAL_TOKEN_ID", "-e", "MODAL_TOKEN_SECRET", 
          "-v", "/path/to/volume", 
          "milkymap/modal_sandbox:0.1", 
          "--transport", "stdio",
          "--app_name", "namespace",
          "--preloaded_secrets", "group0",
          "--preloaded_secrets", "group1"
          ],
        "env": {
          "MODAL_TOKEN_ID": "",
          "MODAL_TOKEN_SECRET": ""
        }
    }
  }
}

Available Tools

The MCP server provides 11 tools for comprehensive sandbox management:

launch_sandbox - Create new Modal sandboxes with custom configuration (Python version, packages, GPU, secrets)
terminate_sandbox - Stop and clean up running sandboxes
list_sandboxes - List all sandboxes in an app namespace with their status
execute_command - Run shell commands in sandboxes and capture output
push_file_to_sandbox - Upload files from local filesystem to sandboxes
pull_file_from_sandbox - Download files from sandboxes to local filesystem
list_directory_contents - List contents of directories within sandboxes
make_directory - Create directories in sandboxes
remove_path - Remove files or directories from sandboxes
read_file_content_from_sandbox - Read file contents directly from sandboxes
write_file_content_to_sandbox - Write content to files within sandboxes