Enables launching Flask web applications with auto port detection and URL generation, allowing users to create and access web-based interfaces.
Supports execution of JavaScript code through the Node.js runtime environment using the sandbox functionality.
Provides comprehensive Python execution capabilities with persistent context, virtual environment support, and automatic artifact capture.
Offers safe shell command execution with security filtering, working directory specification, and configurable timeouts.
Supports launching Streamlit apps with automatic process management and accessible endpoint generation for interactive data applications.
Enhanced Sandbox SDK
Python sandbox execution environment with comprehensive MCP server support, featuring enhanced artifact management, interactive REPL, and Manim animation capabilities.
🎬 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
✨ 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:
This automatically installs and runs the MCP server without manual setup.
Method 2: Local Development Installation
For development, customization, or contributing:
Using uv (Recommended)
Using pip
Method 3: Package Installation
Install from package manager (when available):
🖥️ Usage
Command Line Interface
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:
Method 2: Local Installation
For locally installed versions:
Method 3: HTTP Server Mode
For web-based integrations:
Then configure your application:
Application-Specific Configurations
VS Code/Cursor/Windsurf (using MCP extension):
Jan AI:
OpenHands:
Available MCP Tools
Tool | Description |
| Execute Python code with artifact capture |
| Execute shell commands safely with security filtering |
| List generated artifacts |
| Clean up temporary files |
| Get environment diagnostics |
| Start interactive session |
| Launch Flask/Streamlit apps |
| Maintenance operations |
| Create mathematical animations using Manim |
| List all created Manim animations |
| Clean up specific animation files |
| Get example Manim code snippets |
💡 Examples
Enhanced SDK Usage
Local Python Execution
Remote Python Execution (with microsandbox)
Node.js Execution
Builder Pattern Configuration
MCP Server Examples
Basic Python Execution
Matplotlib Artifact Generation
Flask Web Application
Shell Command Execution
Manim Animation Creation
Error Handling
🏗️ Architecture
Project Structure
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:
FAQ and Limitations - Common issues and sandbox restrictions
Enhanced Features Guide - Advanced capabilities and examples
API Reference - Complete API documentation
🧪 Testing
Run the test suite to verify installation:
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
Fork the repository
Create a feature branch
Run tests:
uv run pytest
Submit a pull request
For development setup:
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
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.
Related MCP Servers
- -securityAlicense-qualityAn 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 -8116MIT License
- -securityFlicense-qualityThis 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 -
- AsecurityAlicenseAqualityA server that provides a persistent Python REPL environment through the MCP protocol, allowing execution of Python code, variable management, and package installation.Last updated -328MIT License
Fused MCP Agentsofficial
-securityAlicense-qualityA 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 -26MIT License