Code Sandbox MCP 🐳
A secure sandbox environment for executing code within Docker containers. This MCP server provides AI applications with a safe and isolated environment for running code while maintaining security through containerization. 
🌟 Features
- Multi-Language Support : Run Python, Go, and Node.js code in isolated Docker containers
- TypeScript Support : Built-in support for TypeScript and JSX/TSX files
- Dependency Management : Automatic handling of project dependencies (pip, go mod, npm)
- Flexible Execution : Custom entrypoints for both single-file code and full projects
- Background Mode : Run long-running services in the background
- Real-time Output : Capture and stream container logs in real-time
🚀 Installation
Prerequisites
- Docker installed and running
Quick Install
Linux, MacOS
curl -fsSL https://raw.githubusercontent.com/Automata-Labs-team/code-sandbox-mcp/main/install.sh | bash
Example output:
Downloading latest release...
Installing to /home/user/.local/share/code-sandbox-mcp/code-sandbox-mcp...
Adding to Claude Desktop configuration...
Added code-sandbox-mcp to /home/user/.config/Claude/claude_desktop_config.json
Installation complete!
You can now use code-sandbox-mcp with Claude Desktop or other AI applications.
Windows
# Run in PowerShell
irm https://raw.githubusercontent.com/Automata-Labs-team/code-sandbox-mcp/main/install.ps1 | iex
The installer will:
- Check for Docker installation
- Download the appropriate binary for your system
- Create Claude Desktop configuration
Manual Installation (Not necesary if automated installation is used)
Download the latest release for your platform from the releases page
Place the binary in a directory in your PATH
Make it executable (Unix-like systems only):
chmod +x code-sandbox-mcp
🛠️ Available Tools
run_code
Executes code snippets in an isolated Docker container.
Parameters:
code (string, required): The code to runlanguage (enum, required): Programming language to use
- Supported values:
python, go, nodejs
- Note: If your Python code requires external dependencies, it is recommended to use the
run_project tool instead. Go and Node.js script dependencies are automatically installed.
Returns:
- Container execution output (stdout + stderr)
Features:
- Automatic dependency detection and installation
- Python: Detects imports and installs via pip
- Node.js: Detects require/import statements and installs via npm
- Go: Detects imports and installs via go get
- Automatic language-specific Docker image selection
- TypeScript/JSX support with appropriate flags
- Special handling for Go (code written to temporary file)
- Real-time output streaming
run_project
Executes a project directory in a containerized environment.
Parameters:
project_dir (string, required): Directory containing the project to runlanguage (enum, required): Programming language to use
- Supported values:
python, go, nodejs
entrypointCmd (string, required): Command to run the project
- Examples:
- Python:
python main.py
- Node.js:
node index.js
- Go:
go run main.go
Returns:
- The resource URI of the container logs.
Features:
- Automatic dependency detection and installation
- Volume mounting of project directory
- Language-specific configuration handling
- Real-time log streaming
🔧 Configuration
Claude Desktop
The installer automatically creates the configuration file. If you need to manually configure it:
Linux
// ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"code-sandbox-mcp": {
"command": "/path/to/code-sandbox-mcp",
"args": [],
"env": {}
}
}
}
macOS
// ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"code-sandbox-mcp": {
"command": "/path/to/code-sandbox-mcp",
"args": [],
"env": {}
}
}
}
Windows
// %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"code-sandbox-mcp": {
"command": "C:\\path\\to\\code-sandbox-mcp.exe",
"args": [],
"env": {}
}
}
}
Other AI Applications
For other AI applications that support MCP servers, configure them to use the code-sandbox-mcp binary as their code execution backend.
🔧 Technical Details
Supported Languages
| Language |
File Extensions |
Docker Image |
| Python |
.py |
python:3.12-slim-bookworm |
| Go |
.go |
golang:1.21-alpine |
| Node.js |
.js, .ts, .tsx, .jsx |
node:23-slim |
Dependency Management
The sandbox automatically detects and installs dependencies:
Python :
- Detects imports like
import requests, from PIL import Image
- Handles aliased imports (e.g.,
PIL → pillow)
- Filters out standard library imports
- Supports both direct imports and
__import__() calls
Node.js :
- Detects
require() statements and ES6 imports
- Handles scoped packages (e.g.,
@org/package)
- Supports dynamic imports (
import())
- Filters out built-in Node.js modules
Go :
- Detects package imports in both single-line and grouped formats
- Handles named and dot imports
- Filters out standard library packages
- Supports external dependencies via
go get
For project execution, the following files are used:
- Python : requirements.txt, pyproject.toml, setup.py
- Go : go.mod
- Node.js : package.json
TypeScript Support
Node.js 23+ includes built-in TypeScript support:
--experimental-strip-types: Enabled by default for .ts files--experimental-transform-types: Used for .tsx files
🔐 Security Features
- Isolated execution environment using Docker containers
- Resource limitations through Docker container constraints
- Separate stdout and stderr streams
- Clean container cleanup after execution
- Project files mounted read-only in containers
🛠️ Development
If you want to build the project locally or contribute to its development, see DEVELOPMENT.md.
📝 License
This project is licensed under the MIT License - see the LICENSE file for details.
