E2B MCP Server

A production-ready Model Context Protocol (MCP) server that integrates AI assistants with E2B's sandboxed code execution environment.

Overview

This MCP server provides secure, sandboxed code execution capabilities for Python and JavaScript, along with file management and package installation features. Built for the Klavis AI coding assignment, it demonstrates enterprise-grade architecture with comprehensive error handling, security validation, and resource management.

Features

Core Tools

1. execute_python - Execute Python code in sandboxed environment
2. execute_javascript - Execute JavaScript/Node.js code
3. create_file - Create files in sandbox
4. read_file - Read files from sandbox
5. list_files - List directory contents
6. install_packages - Install Python (pip) or Node.js (npm) packages
7. get_sandbox_info - Get sandbox status and resource information

Key Features

• Security-First Design: Input validation, output sanitization, and dangerous pattern detection
• Resource Management: Automatic sandbox cleanup, idle timeout handling, and resource monitoring
• Production Ready: Comprehensive logging, error handling, and graceful shutdown
• Multi-language Support: Both Python and JavaScript execution environments
• Persistent Sessions: Reuse sandboxes across tool calls for better performance

Installation

1. Clone and Install Dependencies

   git clone <repository>
   cd my-mcp-server
   npm install
   

2. Set Environment Variables

   export E2B_API_KEY="your-e2b-api-key"
   export LOG_LEVEL="info"  # Optional: debug, info, warn, error
   export NODE_ENV="production"  # Optional: enables file logging
   

3. Build the Project

   npm run build
   

4. Test the Installation

   npm test
   

Usage

As MCP Server

Configure your MCP client to use this server:

{
  "mcpServers": {
    "e2b-server": {
      "command": "node",
      "args": ["/path/to/my-mcp-server/dist/index.js"],
      "env": {
        "E2B_API_KEY": "your-api-key"
      }
    }
  }
}

Development Mode

npm run dev

Direct Testing

# Run comprehensive tests
npm test

# Or run the built server directly
npm start

API Reference

execute_python

Execute Python code in a sandboxed environment.

Parameters:

• code (string, required): Python code to execute
• sandbox_id (string, optional): Specific sandbox ID to reuse

Example:

print("Hello from E2B!")
import numpy as np
data = np.array([1, 2, 3, 4, 5])
print(f"Mean: {np.mean(data)}")

execute_javascript

Execute JavaScript/Node.js code in a sandboxed environment.

Parameters:

• code (string, required): JavaScript code to execute
• sandbox_id (string, optional): Specific sandbox ID to reuse

Example:

console.log("Hello from Node.js!");
const fs = require('fs');
const data = [1, 2, 3, 4, 5];
const mean = data.reduce((a, b) => a + b) / data.length;
console.log(`Mean: ${mean}`);

create_file

Create a file in the sandbox environment.

Parameters:

• path (string, required): File path to create
• content (string, required): File content
• sandbox_id (string, optional): Specific sandbox ID

Example:

{
  "path": "data/example.txt",
  "content": "Hello, E2B MCP Server!"
}

read_file

Read a file from the sandbox environment.

Parameters:

• path (string, required): File path to read
• sandbox_id (string, optional): Specific sandbox ID

list_files

List files in a directory.

Parameters:

• path (string, optional): Directory path (defaults to current directory)
• sandbox_id (string, optional): Specific sandbox ID

install_packages

Install packages in the sandbox environment.

Parameters:

• packages (array of strings, required): Package names to install
• language (string, required): "python" or "javascript"
• sandbox_id (string, optional): Specific sandbox ID

Examples:

{
  "packages": ["numpy", "pandas", "matplotlib"],
  "language": "python"
}

{
  "packages": ["lodash", "axios", "moment"],
  "language": "javascript"
}

get_sandbox_info

Get information about sandbox status and resource usage.

Parameters:

• sandbox_id (string, optional): Specific sandbox ID (if not provided, lists all sandboxes)

Security Features

Input Validation

• Code length limits (50KB max)
• Dangerous pattern detection
• Package name validation
• File path sanitization

Output Sanitization

• ANSI escape code removal
• Secret detection and masking
• Output length limits (10KB max)

Resource Limits

• Execution timeout (30 seconds)
• Idle sandbox cleanup (5 minutes)
• Maximum file size (10MB)
• Package installation limits

Dangerous Pattern Detection

The server monitors for potentially dangerous patterns:

• Network operations (socket, requests, fetch)
• System file access (/etc, /root, /sys)
• Process operations (subprocess, child_process)
• Secret patterns (API keys, passwords)

Architecture

Core Components

1. SandboxService (src/sandbox-manager.ts)

   • Manages E2B sandbox lifecycle
   • Handles resource cleanup and idle timeouts
   • Provides sandbox pooling and reuse

2. E2BTools (src/tools.ts)

   • Implements all MCP tool handlers
   • Integrates with E2B API
   • Handles execution and file operations

3. SecurityValidator (src/security.ts)

   • Input validation and sanitization
   • Pattern detection for dangerous code
   • Output sanitization and secret masking

4. Logger (src/logger.ts)

   • Structured logging with Winston
   • Development and production configurations
   • Security event logging

Error Handling

• Comprehensive try-catch blocks
• Graceful degradation
• Detailed error logging
• User-friendly error messages
• Automatic resource cleanup on failures

Resource Management

• Automatic sandbox cleanup on idle timeout
• Graceful shutdown handlers
• Memory and resource monitoring
• Connection pooling for better performance

Environment Variables

Variable	Required	Default	Description
E2B_API_KEY	Yes	-	Your E2B API key
LOG_LEVEL	No	info	Logging level (debug, info, warn, error)
NODE_ENV	No	development	Environment (enables file logging in production)

Development

Project Structure

src/
├── index.ts           # Main MCP server entry point
├── sandbox-manager.ts # E2B sandbox lifecycle management
├── tools.ts          # MCP tool implementations
├── security.ts       # Security validation and sanitization
├── logger.ts         # Logging configuration
├── types.ts          # TypeScript type definitions
└── test.ts           # Comprehensive test suite

Building

npm run build

Testing

# Mock tests (no API key required) - verify implementation structure
npm run test-mock

# Full functionality tests (requires E2B_API_KEY environment variable)
npm test

Mock Testing: The test-mock script verifies that your implementation is structurally correct without requiring an E2B API key. This is useful for:

• Verifying tool definitions are correct
• Checking method signatures
• Testing implementation structure
• CI/CD environments where API keys aren't available

Full Testing: The test script runs comprehensive functionality tests including:

• Python code execution
• JavaScript code execution
• File operations (create, read, list)
• Package installation (Python & JavaScript)
• Sandbox management
• Error handling

Linting and Type Checking

npx tsc --noEmit

Production Deployment

Docker Deployment

Create a Dockerfile:

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
ENV NODE_ENV=production
CMD ["npm", "start"]

Environment Setup

# Production environment variables
export NODE_ENV=production
export LOG_LEVEL=info
export E2B_API_KEY=your-production-api-key

Monitoring

The server provides structured JSON logging suitable for log aggregation services:

{
  "level": "info",
  "message": "Executing Python code in sandbox abc-123",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "service": "e2b-mcp-server"
}

Performance Considerations

• Sandbox Reuse: Sandboxes are reused across tool calls to reduce latency
• Idle Cleanup: Automatic cleanup after 5 minutes of inactivity
• Output Limits: Output is truncated at 10KB to prevent memory issues
• Timeout Management: 30-second execution timeout with graceful error handling
• Resource Monitoring: Built-in sandbox resource usage tracking

Troubleshooting

Common Issues

1. "E2B_API_KEY environment variable is required"

   • Ensure your E2B API key is set in environment variables
   • Verify the key is valid and has appropriate permissions

2. "Sandbox creation failed"

   • Check E2B service status
   • Verify API key permissions
   • Check network connectivity

3. "Security validation failed"

   • Review code for dangerous patterns
   • Check file paths for directory traversal
   • Verify package names follow naming conventions

4. "Execution timeout"

   • Code took longer than 30 seconds to execute
   • Consider optimizing code or breaking into smaller chunks

Fixed Issues (Latest Update)

✅ Code Execution Issue Resolved

The previous issue with Jupyter kernel port (49999) not being open has been completely resolved. The server now uses E2B's latest v1.5.1 SDK which provides direct code execution without relying on Jupyter kernels.

What was fixed:

• Updated from legacy Jupyter-based execution to E2B's modern code execution API
• Fixed execute_python ✅ - Now works with E2B v1.5.1 direct execution
• Fixed execute_javascript ✅ - Now works with proper Node.js wrapping
• Fixed install_packages ✅ - Now works for both Python (pip) and JavaScript (npm)

All features now working:

• ✅ execute_python - Execute Python code in sandboxed environment
• ✅ execute_javascript - Execute JavaScript/Node.js code
• ✅ create_file - Create files in sandbox
• ✅ read_file - Read files from sandbox
• ✅ list_files - List directory contents
• ✅ install_packages - Install Python (pip) or Node.js (npm) packages
• ✅ get_sandbox_info - Get sandbox status and resource information

Logging

Enable debug logging for detailed troubleshooting:

export LOG_LEVEL=debug
npm start

Contributing

This project follows TypeScript strict mode and includes comprehensive error handling. When contributing:

1. Follow the existing code style
2. Add appropriate error handling
3. Include security validation for new features
4. Update tests for new functionality
5. Add logging for important operations

License

MIT License - see LICENSE file for details.

Support

For issues specific to this MCP server implementation, please check the troubleshooting section above. For E2B-related issues, consult the E2B documentation.