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
- macOS:
-
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.pyandsrc/sandbox/file_interface.py - Add the new interpreter type to the
src/sandbox/interpreter_factory.py - Configure the environment variable
INTERPRETER_TYPEto 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 interpretersfile_interface.py: Abstract interface for file operationsinterpreter_factory.py: Factory for creating code interpreter instances
E2B Implementation (src/sandbox/e2b/)
e2b_interpreter.py: E2B implementation of the code interpretere2b_file_interface.py: E2B implementation of file operations
Tools (tools/)
sandbox_tools.py: Tools for sandbox administrationcode_execution_tools.py: Tools for code executionfile_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