MCP Code Sandbox Server

An extensible Message Communication Protocol (MCP) server that provides secure code execution capabilities in isolated sandbox environments. This server follows the MCP standard, making it compatible with Claude for Desktop and other MCP clients.

Features

Create isolated sandbox environments for code execution
Execute Python code securely
Perform file operations (listing, reading, writing)
Install Python packages in the sandbox
Extensible architecture with abstracted code interpreter interface
Modular design with clean separation of concerns

Architecture

The server is built with a modular, extensible architecture:

Core Components

Abstract Interpreter Interface: Allows different code execution backends to be integrated
Sandbox Administration: Tools for creating and managing sandbox environments
Code Execution: Tools for running code and installing packages
File Operations: Tools for managing files within sandboxes

Project Structure

├── src/
│   └── sandbox/
│       ├── __pycache__/
│       ├── e2b/
│       │   ├── __pycache__/
│       │   ├── __init__.py
│       │   ├── e2b_file_interface.py
│       │   └── e2b_interpreter.py
│       ├── __init__.py
│       ├── code_interpreter.py
│       ├── file_interface.py
│       └── interpreter_factory.py
├── tools/
│   ├── __pycache__/
│   ├── __init__.py
│   ├── code_execution_tools.py
│   ├── file_tools.py
│   └── sandbox_tools.py
├── main.py
├── .env
├── .gitignore
├── .python-version
├── pyproject.toml
├── README.md
└── uv.lock

Prerequisites

Python 3.10 or higher
E2B API key (for the default E2B interpreter)

Installation

Clone this repository:
git clone https://github.com/yourusername/mcp-code-sandbox.git cd mcp-code-sandbox
Set up a virtual environment:
# Using venv python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # Or using uv (recommended) uv init uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate
Install the required packages:
# Using pip pip install fastmcp python-dotenv e2b-code-interpreter # Or using uv uv add fastmcp python-dotenv e2b-code-interpreter
Configure environment variables:
# Create a .env file with the following variables E2B_API_KEY=your_e2b_api_key_here INTERPRETER_TYPE=e2b # Default, can be changed to other implemented interpreters

Usage

Running the Server Standalone

You can run the server directly from the command line:

python main.py

This will start the server using the stdio transport, making it compatible with Claude for Desktop.

Using with Claude for Desktop

Make sure you have the latest version of Claude for Desktop installed
Open your Claude for Desktop configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add your code sandbox server configuration:
{ "mcpServers": { "code-sandbox": { "command": "python", "args": [ "/ABSOLUTE/PATH/TO/main.py" ] } } }
Or if you're using uv:
{ "mcpServers": { "code-sandbox": { "command": "uv", "args": [ "--directory", "/ABSOLUTE/PATH/TO/PROJECT_DIRECTORY", "run", "main.py" ] } } }
Save the file and restart Claude for Desktop

Available Tools

The server provides the following tools:

Sandbox Administration

create_sandbox: Create a new sandbox environment
close_sandbox: Close and clean up a sandbox
get_sandbox_status: Check status of sandboxes

Code Execution

execute_code: Run Python code in a sandbox
install_package: Install a Python package
create_run_close: All-in-one tool that creates a sandbox, runs code, and cleans up

File Operations

list_files: List files in the sandbox
read_file: Read the contents of a file
write_file: Write content to a file
upload_file: Upload a file to the sandbox

Extending with New Interpreters

The system is designed to be extensible. To add a new code interpreter:

Create a new directory under src/sandbox/ for your interpreter implementation
Implement the interfaces defined in src/sandbox/code_interpreter.py and src/sandbox/file_interface.py
Add the new interpreter type to the src/sandbox/interpreter_factory.py
Configure the environment variable INTERPRETER_TYPE to your new interpreter

Example of implementing a new interpreter:

# src/sandbox/my_backend/my_interpreter.py
from src.sandbox.code_interpreter import CodeInterpreter, ExecutionResult
from src.sandbox.file_interface import FileInterface

class MyFileInterface(FileInterface):
    # Implement the required methods
    
class MyInterpreter(CodeInterpreter):
    # Implement the required methods

# Update src/sandbox/interpreter_factory.py to include your new interpreter

Module Descriptions

Sandbox Core (`src/sandbox/`)

code_interpreter.py: Abstract base class for code interpreters
file_interface.py: Abstract interface for file operations
interpreter_factory.py: Factory for creating code interpreter instances

E2B Implementation (`src/sandbox/e2b/`)

e2b_interpreter.py: E2B implementation of the code interpreter
e2b_file_interface.py: E2B implementation of file operations

Tools (`tools/`)

sandbox_tools.py: Tools for sandbox administration
code_execution_tools.py: Tools for code execution
file_tools.py: Tools for file operations

Main Application

main.py: Main application entry point

Troubleshooting

If you encounter issues:

Make sure you have the correct API key for your chosen interpreter
Check the logs for detailed error messages
Verify that all required packages are installed
Ensure Claude for Desktop is configured with the correct path to your script

Security Considerations

The code execution happens in sandboxed environments for safety
Do not use this server to execute untrusted code in production environments
The server does not currently implement authentication - it should only be used in trusted environments

License

MIT License