Skip to main content
Glama

Sandbox MCP

by scooter-lacroix
GitHub
Python
Apache 2.0
3
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Enhanced Sandbox SDK

Python sandbox execution environment with comprehensive MCP server support, featuring enhanced artifact management, interactive REPL, and Manim animation capabilities.

Python 3.9+ FastMCP License

🎬 Demo: Manim Animation in Action

See the Sandbox MCP server creating beautiful mathematical animations with Manim:

Alternative formats: MP4 Video | GIF Animation

Example: 3D mathematical animation generated automatically by the sandbox

🚀 Quick Start

# Clone the repository git clone https://github.com/scooter-lacroix/sandbox-mcp.git cd sandbox-mcp # Install with uv (recommended) uv venv && uv pip install -e . # Run the MCP server uv run sandbox-server-stdio

✨ Features

🔧 Enhanced Python Execution

  • Code Validation: Automatic input validation and formatting

  • Virtual Environment: Auto-detects and activates .venv

  • Persistent Context: Variables persist across executions

  • Enhanced Error Handling: Detailed diagnostics with colored output

  • Interactive REPL: Real-time Python shell with tab completion

🎨 Intelligent Artifact Management

  • Automatic Capture: Matplotlib plots and PIL images

  • Categorization: Smart file type detection and organization

  • Multiple Formats: JSON, CSV, and structured output

  • Recursive Scanning: Deep directory traversal

  • Smart Cleanup: Configurable cleanup by type or age

🎬 Manim Animation Support

  • Pre-compiled Examples: One-click animation execution

  • Quality Control: Multiple rendering presets

  • Video Generation: Auto-saves MP4 animations

  • Example Library: Built-in templates and tutorials

  • Environment Verification: Automatic dependency checking

🌐 Web Application Hosting

  • Flask & Streamlit: Launch web apps with auto port detection

  • Process Management: Track and manage running servers

  • URL Generation: Returns accessible endpoints

🔒 Security & Safety

  • Command Filtering: Blocks dangerous operations

  • Sandboxed Execution: Isolated environment

  • Timeout Control: Configurable execution limits

  • Resource Monitoring: Memory and CPU usage tracking

🔌 MCP Integration

  • Dual Transport: HTTP and stdio support

  • LM Studio Ready: Drop-in AI model integration

  • FastMCP Powered: Modern MCP implementation

  • Comprehensive Tools: 12+ available MCP tools

📦 Installation

Prerequisites

  • Python 3.9+

  • uv (recommended) or pip

Method 1: Direct Git Installation (Recommended)

For immediate use with AI applications like LM Studio, Claude Desktop, or VS Code:

uvx git+https://github.com/scooter-lacroix/sandbox-mcp.git

This automatically installs and runs the MCP server without manual setup.

Method 2: Local Development Installation

For development, customization, or contributing:

Using uv (Recommended)

git clone https://github.com/scooter-lacroix/sandbox-mcp.git cd sandbox-mcp uv venv uv pip install -e .

Using pip

git clone https://github.com/scooter-lacroix/sandbox-mcp.git cd sandbox-mcp python -m venv .venv source .venv/bin/activate # Linux/Mac # .venv\Scripts\activate # Windows pip install -e .

Method 3: Package Installation

Install from package manager (when available):

# Using uv uvx sandbox-mcp # Using pip pip install sandbox-mcp

🖥️ Usage

Command Line Interface

# Start HTTP server (web integration) sandbox-server # Start stdio server (LM Studio integration) sandbox-server-stdio

MCP Integration

The Sandbox MCP server supports multiple integration methods:

Method 1: Direct Git Integration (Recommended)

For LM Studio, Claude Desktop, VS Code, and other MCP-compatible applications:

{ "mcpServers": { "sandbox": { "command": "uvx", "args": ["git+https://github.com/scooter-lacroix/sandbox-mcp.git"], "env": {}, "start_on_launch": true } } }

Method 2: Local Installation

For locally installed versions:

{ "mcpServers": { "sandbox": { "command": "sandbox-server-stdio", "args": [], "env": {}, "start_on_launch": true } } }

Method 3: HTTP Server Mode

For web-based integrations:

# Start HTTP server python -m sandbox.mcp_sandbox_server --port 8765

Then configure your application:

{ "mcpServers": { "sandbox": { "transport": "http", "url": "http://localhost:8765/mcp", "headers": { "Authorization": "Bearer your-token-here" } } } }

Application-Specific Configurations

VS Code/Cursor/Windsurf (using MCP extension):

{ "mcp.servers": { "sandbox": { "command": "sandbox-server-stdio", "args": [], "env": {}, "transport": "stdio" } } }

Jan AI:

{ "mcp_servers": { "sandbox": { "command": "sandbox-server-stdio", "args": [], "env": {} } } }

OpenHands:

{ "mcp": { "servers": { "sandbox": { "command": "sandbox-server-stdio", "args": [], "env": {} } } } }

Available MCP Tools

Tool

Description

execute

Execute Python code with artifact capture

shell_execute

Execute shell commands safely with security filtering

list_artifacts

List generated artifacts

cleanup_artifacts

Clean up temporary files

get_execution_info

Get environment diagnostics

start_repl

Start interactive session

start_web_app

Launch Flask/Streamlit apps

cleanup_temp_artifacts

Maintenance operations

create_manim_animation

Create mathematical animations using Manim

list_manim_animations

List all created Manim animations

cleanup_manim_animation

Clean up specific animation files

get_manim_examples

Get example Manim code snippets

💡 Examples

Enhanced SDK Usage

Local Python Execution

import asyncio from sandbox import PythonSandbox async def local_example(): async with PythonSandbox.create_local(name="my-sandbox") as sandbox: # Execute Python code result = await sandbox.run("print('Hello from local sandbox!')") print(await result.output()) # Execute code with artifacts plot_code = """ import matplotlib.pyplot as plt import numpy as np x = np.linspace(0, 10, 100) y = np.sin(x) plt.figure(figsize=(8, 6)) plt.plot(x, y) plt.title('Sine Wave') plt.show() # Automatically captured as artifact """ result = await sandbox.run(plot_code) print(f"Artifacts created: {result.artifacts}") # Execute shell commands cmd_result = await sandbox.command.run("ls", ["-la"]) print(await cmd_result.output()) asyncio.run(local_example())

Remote Python Execution (with microsandbox)

import asyncio from sandbox import PythonSandbox async def remote_example(): async with PythonSandbox.create_remote( server_url="http://127.0.0.1:5555", api_key="your-api-key", name="remote-sandbox" ) as sandbox: # Execute Python code in secure microVM result = await sandbox.run("print('Hello from microVM!')") print(await result.output()) # Get sandbox metrics metrics = await sandbox.metrics.all() print(f"CPU usage: {metrics.get('cpu_usage', 0)}%") print(f"Memory usage: {metrics.get('memory_usage', 0)} MB") asyncio.run(remote_example())

Node.js Execution

import asyncio from sandbox import NodeSandbox async def node_example(): async with NodeSandbox.create( server_url="http://127.0.0.1:5555", api_key="your-api-key", name="node-sandbox" ) as sandbox: # Execute JavaScript code js_code = """ console.log('Hello from Node.js!'); const sum = [1, 2, 3, 4, 5].reduce((a, b) => a + b, 0); console.log(`Sum: ${sum}`); """ result = await sandbox.run(js_code) print(await result.output()) asyncio.run(node_example())

Builder Pattern Configuration

import asyncio from sandbox import LocalSandbox, SandboxOptions async def builder_example(): config = (SandboxOptions.builder() .name("configured-sandbox") .memory(1024) .cpus(2.0) .timeout(300.0) .env("DEBUG", "true") .build()) async with LocalSandbox.create(**config.__dict__) as sandbox: result = await sandbox.run("import os; print(os.environ.get('DEBUG'))") print(await result.output()) # Should print: true asyncio.run(builder_example())

MCP Server Examples

Basic Python Execution

# Execute simple code result = execute(code="print('Hello, World!')")

Matplotlib Artifact Generation

code = """ import matplotlib.pyplot as plt import numpy as np # Generate plot x = np.linspace(0, 10, 100) y = np.sin(x) plt.figure(figsize=(8, 6)) plt.plot(x, y, 'b-', linewidth=2) plt.title('Sine Wave') plt.xlabel('x') plt.ylabel('sin(x)') plt.grid(True) plt.show() # Automatically captured as artifact """ result = execute(code) # Returns JSON with base64-encoded PNG

Flask Web Application

flask_code = """ from flask import Flask, jsonify app = Flask(__name__) @app.route('/') def home(): return '<h1>Sandbox Flask App</h1>' @app.route('/api/status') def status(): return jsonify({"status": "running", "server": "sandbox"}) """ result = start_web_app(flask_code, "flask") # Returns URL where app is accessible

Shell Command Execution

# Install packages via shell result = shell_execute("uv pip install matplotlib") # Check environment result = shell_execute("which python") # List directory contents result = shell_execute("ls -la") # Custom working directory and timeout result = shell_execute( "find . -name '*.py' | head -10", working_directory="/path/to/search", timeout=60 )

Manim Animation Creation

# Simple circle animation manim_code = """ from manim import * class SimpleCircle(Scene): def construct(self): circle = Circle() circle.set_fill(PINK, opacity=0.5) self.play(Create(circle)) self.wait(1) """ result = create_manim_animation(manim_code, quality="medium_quality") # Returns JSON with video path and metadata # Mathematical graph visualization math_animation = """ from manim import * class GraphPlot(Scene): def construct(self): axes = Axes( x_range=[-3, 3, 1], y_range=[-3, 3, 1], x_length=6, y_length=6 ) axes.add_coordinates() graph = axes.plot(lambda x: x**2, color=BLUE) graph_label = axes.get_graph_label(graph, label="f(x) = x^2") self.play(Create(axes)) self.play(Create(graph)) self.play(Write(graph_label)) self.wait(1) """ result = create_manim_animation(math_animation, quality="high_quality") # List all animations animations = list_manim_animations() # Get example code snippets examples = get_manim_examples()

Error Handling

# Import error with detailed diagnostics result = execute(code="import nonexistent_module") # Returns structured error with sys.path info # Security-blocked shell command result = shell_execute("rm -rf /") # Returns security error with blocked pattern info

🏗️ Architecture

Project Structure

sandbox-mcp/ ├── src/ │ └── sandbox/ # Main package │ ├── __init__.py # Package initialization │ ├── mcp_sandbox_server.py # HTTP MCP server │ ├── mcp_sandbox_server_stdio.py # stdio MCP server │ ├── server/ # Server modules │ │ ├── __init__.py │ │ └── main.py │ └── utils/ # Utility modules │ ├── __init__.py │ └── helpers.py ├── tests/ │ ├── test_integration.py # Main test suite │ └── test_simple_integration.py ├── pyproject.toml # Package configuration ├── README.md # This file ├── .gitignore └── uv.lock # Dependency lock file

Core Components

ExecutionContext

Manages the execution environment:

  • Project Root Detection: Dynamic path resolution

  • Virtual Environment: Auto-detection and activation

  • sys.path Management: Intelligent path handling

  • Artifact Management: Temporary directory lifecycle

  • Global State: Persistent execution context

Monkey Patching System

Non-intrusive artifact capture:

  • matplotlib.pyplot.show(): Intercepts and saves plots

  • PIL.Image.show(): Captures image displays

  • Conditional Patching: Only applies if libraries available

  • Original Functionality: Preserved through wrapper functions

MCP Integration

FastMCP-powered server with:

  • Dual Transport: HTTP and stdio protocols

  • Tool Registry: 7 available MCP tools

  • Streaming Support: Ready for real-time interaction

  • Error Handling: Structured error responses

📚 Documentation

For comprehensive usage information, troubleshooting guides, and advanced features:

🧪 Testing

Run the test suite to verify installation:

uv run pytest tests/ -v

Test categories include:

  • Package import and sys.path tests

  • Error handling and ImportError reporting

  • Artifact capture (matplotlib/PIL)

  • Web application launching

  • Virtual environment detection

🤝 Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Run tests: uv run pytest

  4. Submit a pull request

For development setup:

uv venv && uv pip install -e ".[dev]"

License

Apache License

Attribution

This project includes minor inspiration from:

  • Microsandbox - Referenced for secure microVM isolation concepts

The majority of the functionality in this project is original implementation focused on MCP server integration and enhanced Python execution environments.

Changelog

v0.3.0 (Enhanced SDK Release)

  • 🚀 Enhanced SDK: Complete integration with microsandbox functionality

  • 🔄 Unified API: Single interface for both local and remote execution

  • 🛡️ MicroVM Support: Secure remote execution via microsandbox server

  • 🌐 Multi-Language: Python and Node.js execution environments

  • 🏗️ Builder Pattern: Fluent configuration API with SandboxOptions

  • 📊 Metrics & Monitoring: Real-time resource usage tracking

  • ⚡ Async/Await: Modern Python async support throughout

  • 🔒 Enhanced Security: Improved command filtering and validation

  • 📦 Artifact Management: Comprehensive file artifact handling

  • 🎯 Command Execution: Safe shell command execution with timeouts

  • 🔧 Configuration: Flexible sandbox configuration options

  • 📝 Documentation: Comprehensive examples and usage guides

v0.2.0

  • Manim Integration: Complete mathematical animation support

  • 4 New MCP Tools: create_manim_animation, list_manim_animations, cleanup_manim_animation, get_manim_examples

  • Quality Control: Multiple animation quality presets

  • Video Artifacts: Auto-saves MP4 animations to artifacts directory

  • Example Library: Built-in Manim code examples

  • Virtual Environment Manim: Uses venv-installed Manim executable

v0.1.0

  • Initial enhanced package structure

  • Dynamic project root detection

  • Robust virtual environment integration

  • Enhanced error handling with detailed tracebacks

  • Artifact management with matplotlib/PIL support

  • Web application launching (Flask/Streamlit)

  • Comprehensive test suite

  • MCP server integration (HTTP and stdio)

  • CLI entry points

  • LM Studio compatibility

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Production-ready MCP server for secure Python code execution with artifact capture, virtual environment support, and LM Studio integration.

  1. 🎬 Demo: Manim Animation in Action
    1. 🚀 Quick Start
      1. ✨ Features
        1. 🔧 Enhanced Python Execution
        2. 🎨 Intelligent Artifact Management
        3. 🎬 Manim Animation Support
        4. 🌐 Web Application Hosting
        5. 🔒 Security & Safety
        6. 🔌 MCP Integration
      2. 📦 Installation
        1. Prerequisites
        2. Method 1: Direct Git Installation (Recommended)
        3. Method 2: Local Development Installation
        4. Method 3: Package Installation
      3. 🖥️ Usage
        1. Command Line Interface
        2. MCP Integration
        3. Available MCP Tools
      4. 💡 Examples
        1. Enhanced SDK Usage
        2. MCP Server Examples
        3. Matplotlib Artifact Generation
        4. Flask Web Application
        5. Shell Command Execution
        6. Manim Animation Creation
        7. Error Handling
      5. 🏗️ Architecture
        1. Project Structure
        2. Core Components
      6. 📚 Documentation
        1. 🧪 Testing
          1. 🤝 Contributing
            1. License
              1. Attribution
                1. Changelog
                  1. v0.3.0 (Enhanced SDK Release)
                  2. v0.2.0
                  3. v0.1.0

                Related MCP Servers

                • MySQL MCP Server

                  kevinwatt
                  -
                  security
                  A
                  license
                  -
                  quality
                  An MCP server that integrates with MySQL databases, enabling secure read and write operations through LLM-driven interfaces with support for transaction handling and performance monitoring.
                  Last updated -
                  81
                  16
                  MIT License

                • Lodestar MCP Server

                  kanlanc
                  -
                  security
                  F
                  license
                  -
                  quality
                  This is an MCP server that facilitates building tools for interacting with various APIs and workflows, supporting Python-based development with potential for customizable prompts and user configurations.
                  Last updated -

                • Python REPL MCP Server

                  hdresearch
                  A
                  security
                  A
                  license
                  A
                  quality
                  A server that provides a persistent Python REPL environment through the MCP protocol, allowing execution of Python code, variable management, and package installation.
                  Last updated -
                  3
                  28
                  MIT License

                • Fused MCP Agentsofficial

                  fusedio
                  -
                  security
                  A
                  license
                  -
                  quality
                  A Python-based MCP server that allows Claude and other LLMs to execute arbitrary Python code directly through your desktop Claude app, enabling data scientists to connect LLMs to APIs and executable code.
                  Last updated -
                  26
                  MIT License
                  • Apple
                  • Linux

                View all related MCP servers

                New MCP Servers

                MCP directory API

                We provide all the information about MCP servers via our MCP API.

                curl -X GET 'https://glama.ai/api/mcp/v1/servers/scooter-lacroix/sandbox-mcp'

                If you have feedback or need assistance with the MCP directory API, please join our Discord server