E2B Sandbox MCP Server

🚀 AI-Powered Computer Use Through Secure Cloud Sandboxes

A powerful Model Context Protocol (MCP) server that enables AI assistants to create, control, and interact with virtual desktop environments through E2B's secure cloud sandboxes. Perfect for AI agents that need to perform computer tasks, web automation, or visual testing.

✨ Features

• 🖥️ Virtual Desktop Management: Create Ubuntu 22.04 desktop sandboxes in seconds
• 🎮 Complete Computer Control: Click, type, drag, scroll, and keyboard shortcuts
• 📺 Live VNC Streaming: Real-time desktop viewing through secure web streams
• 📸 Screenshot Capture: AI-ready desktop screenshots for vision processing
• 🔄 Lifecycle Management: Automatic cleanup and resource management
• 🛡️ Secure Isolation: Completely isolated environments with no host access
• 🔧 MCP Standard: Fully compatible with Model Context Protocol
• ⚡ High Performance: Optimized for AI workloads and real-time interaction

🎯 Use Cases

• AI Agent Automation: Let AI agents perform complex computer tasks
• Web Scraping & Testing: Automated browser interactions and testing
• Application Testing: Visual regression testing and UI automation
• Data Entry Automation: Automate form filling and data processing
• Research & Analysis: AI-powered information gathering from desktop apps
• Training Data Generation: Capture interaction sequences for ML training

📋 Prerequisites

• Node.js (v18 or higher)
• E2B API Key (Free tier available)
• TypeScript knowledge (for development)

🚀 Quick Start

1. Installation

# Clone the repository
git clone https://github.com/your-username/e2b-sandbox-mcp.git
cd e2b-sandbox-mcp

# Install dependencies
npm install

# Build TypeScript
npm run build

2. Configuration

Create a .env file or set environment variables:

E2B_API_KEY=your_e2b_api_key_here

Get your E2B API key:

1. Visit E2B Dashboard
2. Sign up/log in
3. Navigate to "API Keys"
4. Create a new API key

3. Running the Server

# Start the MCP server
npm start

# Development mode with hot reload
npm run dev

# Debug mode
npm run inspect

4. MCP Client Integration

Add to your MCP configuration file (e.g., mcp.json):

{
  "mcpServers": {
    "e2b-sandbox": {
      "command": "node",
      "args": ["/PATH_TO/e2b-sandbox-mcp/dist/index.js"],
      "env": {
        "OPEN_AI_API_KEY": "YOUR_OPEN_AI_API_KEY",
        "E2B_API_KEY": "YOUR_E2B_API_KEY"
      }
    }
  }
}

📚 API Reference

MCP Tools

create_sandbox

Creates a new E2B desktop sandbox instance.

Parameters:

• resolution (optional): Array of [width, height]. Default: [1920, 1080]
• timeout (optional): Timeout in milliseconds. Default: 600000 (10 minutes)

Example:

{
  "name": "create_sandbox",
  "arguments": {
    "resolution": [1920, 1080],
    "timeout": 600000
  }
}

Response:

{
  "sandboxId": "imy7xu1l122itq99pp4rn-9886af4b",
  "streamUrl": "https://6080-sandbox-id.e2b.app/vnc.html?autoconnect=true&resize=scale",
  "resolution": [1920, 1080],
  "status": "created",
  "message": "Sandbox created successfully"
}

execute_computer_action

Execute computer actions on the sandbox desktop.

Parameters:

• sandboxId: The sandbox ID to execute action on
• action: Action object with type and parameters

Supported Actions:

Action Type	Description	Parameters
click	Click at coordinates	x, y, button (left/right/middle)
double_click	Double-click at coordinates	x, y, button
type	Type text	text
keypress	Press keyboard keys	keys (e.g., "Ctrl+c", "Return")
move	Move mouse cursor	x, y
scroll	Scroll vertically	scroll_y, x, y
drag	Drag from point A to B	path (array of {x, y} points)
screenshot	Take screenshot	None

Examples:

// Click example
{
  "name": "execute_computer_action",
  "arguments": {
    "sandboxId": "sandbox-id",
    "action": {
      "type": "click",
      "x": 100,
      "y": 200,
      "button": "left"
    }
  }
}

// Type text example
{
  "name": "execute_computer_action",
  "arguments": {
    "sandboxId": "sandbox-id",
    "action": {
      "type": "type",
      "text": "Hello, World!"
    }
  }
}

// Keyboard shortcut example
{
  "name": "execute_computer_action",
  "arguments": {
    "sandboxId": "sandbox-id",
    "action": {
      "type": "keypress",
      "keys": "Ctrl+c"
    }
  }
}

// Drag example
{
  "name": "execute_computer_action",
  "arguments": {
    "sandboxId": "sandbox-id",
    "action": {
      "type": "drag",
      "path": [
        {"x": 100, "y": 100},
        {"x": 200, "y": 200}
      ]
    }
  }
}

get_stream_url

Get the VNC stream URL for viewing the desktop.

{
  "name": "get_stream_url",
  "arguments": {
    "sandboxId": "sandbox-id"
  }
}

get_screenshot

Capture a screenshot of the desktop.

{
  "name": "get_screenshot",
  "arguments": {
    "sandboxId": "sandbox-id"
  }
}

Response:

{
  "screenshot": "base64-encoded-image-data",
  "format": "png",
  "timestamp": "2024-01-15T10:30:00Z"
}

cleanup_sandbox

Clean up and destroy a sandbox instance.

{
  "name": "cleanup_sandbox",
  "arguments": {
    "sandboxId": "sandbox-id"
  }
}

list_sandboxes

List all active sandbox instances.

{
  "name": "list_sandboxes",
  "arguments": {}
}

🏗️ Integration Examples

Basic Usage

import { MCPClient } from "@modelcontextprotocol/sdk/client/index.js";

class ComputerUseClient {
  private mcpClient: MCPClient;

  async createDesktopSession() {
    // Create a new sandbox
    const result = await this.mcpClient.callTool({
      name: "create_sandbox",
      arguments: {
        resolution: [1920, 1080],
        timeout: 600000,
      },
    });

    const response = JSON.parse(result.content[0].text);
    return {
      sandboxId: response.sandboxId,
      streamUrl: response.streamUrl,
    };
  }

  async automateWebBrowsing(sandboxId: string, url: string) {
    // Open Firefox browser
    await this.mcpClient.callTool({
      name: "execute_computer_action",
      arguments: {
        sandboxId,
        action: { type: "keypress", keys: "Meta+t" },
      },
    });

    // Type URL
    await this.mcpClient.callTool({
      name: "execute_computer_action",
      arguments: {
        sandboxId,
        action: { type: "type", text: url },
      },
    });

    // Press Enter
    await this.mcpClient.callTool({
      name: "execute_computer_action",
      arguments: {
        sandboxId,
        action: { type: "keypress", keys: "Return" },
      },
    });
  }
}

React Frontend Integration

import React, { useState, useEffect } from "react";

interface DesktopViewerProps {
  streamUrl: string;
}

function DesktopViewer({ streamUrl }: DesktopViewerProps) {
  return (
    <div className="desktop-container">
      <iframe
        src={streamUrl}
        className="w-full h-full border-0"
        allow="clipboard-read; clipboard-write; fullscreen"
        title="E2B Desktop Sandbox"
        style={{ minHeight: "600px" }}
      />
    </div>
  );
}

function App() {
  const [sandboxData, setSandboxData] = useState(null);

  const createSandbox = async () => {
    // Your MCP client call here
    const response = await mcpClient.callTool({
      name: "create_sandbox",
      arguments: { resolution: [1920, 1080] },
    });
    setSandboxData(JSON.parse(response.content[0].text));
  };

  return (
    <div className="app">
      <button onClick={createSandbox} className="btn-primary">
        Create Desktop Sandbox
      </button>

      {sandboxData && <DesktopViewer streamUrl={sandboxData.streamUrl} />}
    </div>
  );
}

AI Agent Integration

class AIComputerAgent {
  constructor(private mcpClient: MCPClient) {}

  async performTask(sandboxId: string, instruction: string) {
    // 1. Take screenshot to understand current state
    const screenshot = await this.mcpClient.callTool({
      name: "get_screenshot",
      arguments: { sandboxId },
    });

    // 2. Process with AI to determine next actions
    const actions = await this.analyzeAndPlan(
      instruction,
      screenshot.content[0].text
    );

    // 3. Execute planned actions
    for (const action of actions) {
      await this.mcpClient.callTool({
        name: "execute_computer_action",
        arguments: { sandboxId, action },
      });

      // Small delay between actions
      await new Promise((resolve) => setTimeout(resolve, 500));
    }
  }

  private async analyzeAndPlan(instruction: string, screenshot: string) {
    // Your AI logic here (OpenAI, Anthropic, etc.)
    // Return array of computer actions
    return [
      { type: "click", x: 100, y: 200, button: "left" },
      { type: "type", text: "Hello World" },
    ];
  }
}

🏛️ Architecture

System Overview

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   AI Assistant  │    │  MCP Client     │    │  Your App       │
│                 │    │                 │    │                 │
│  • Claude       │◄──►│  • Tool Calls   │◄──►│  • Frontend     │
│  • GPT-4        │    │  • Responses    │    │  • Backend      │
│  • Custom       │    │                 │    │  • API          │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                 │
                                 ▼
                    ┌─────────────────┐
                    │ E2B Sandbox MCP │
                    │     Server      │
                    │                 │
                    │ • Sandbox Mgmt  │
                    │ • Action Exec   │
                    │ • Stream URLs   │
                    │ • Screenshots   │
                    └─────────────────┘
                                 │
                                 ▼
                    ┌─────────────────┐
                    │  E2B Cloud      │
                    │   Sandboxes     │
                    │                 │
                    │ • Ubuntu 22.04  │
                    │ • VNC Streaming │
                    │ • Isolation     │
                    │ • Auto Cleanup  │
                    └─────────────────┘

Key Components

• MCP Server: Handles tool calls and manages E2B API interactions
• Sandbox Manager: Creates, tracks, and cleans up sandbox instances
• Computer Use Tools: Executes mouse, keyboard, and system actions
• Stream Manager: Provides VNC URLs for real-time desktop viewing
• Action Executor: Translates MCP actions to E2B desktop commands

📁 Project Structure

e2b-sandbox-mcp/
├── src/
│   ├── index.ts              # Main MCP server entry point
│   ├── sandbox-manager.ts    # E2B sandbox lifecycle management
│   └── computer-use-tools.ts # Computer action implementations
├── examples/
│   ├── simple-test.js        # Basic testing script
│   ├── client-integration.ts # Advanced MCP client example
│   └── web-integration/      # Web app integration example
├── dist/                     # Compiled JavaScript output
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
└── README.md                 # This file

🧪 Testing

Run Examples

# Test basic functionality
npm test

# Run web integration example
cd examples/web-integration
npm install
npm start

Manual Testing

# Start MCP server in debug mode
npm run inspect

# In another terminal, test tool calls
node examples/simple-test.js

🔧 Development

Setup Development Environment

# Clone and setup
git clone https://github.com/your-username/e2b-sandbox-mcp.git
cd e2b-sandbox-mcp

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Edit .env with your E2B API key

# Start development server
npm run dev

Available Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run dev - Start development server with hot reload
• npm start - Start production server
• npm run inspect - Start with Node.js debugger
• npm test - Run test scripts
• npm run setup - Setup and test installation

Adding New Features

1. New Computer Actions: Add to src/computer-use-tools.ts
2. Enhanced Management: Modify src/sandbox-manager.ts
3. API Extensions: Update src/index.ts with new tool definitions

🐛 Troubleshooting

Common Issues

Problem	Solution
E2B_API_KEY not found	Set environment variable or pass --e2b-api-key argument
Sandbox creation fails	Check E2B API key validity and account quota
Actions not executing	Verify sandbox is active with list_sandboxes
Stream URL not working	Ensure sandbox supports VNC (desktop template)
High memory usage	Implement proper sandbox cleanup after use

Debug Mode

# Enable detailed logging
DEBUG=* npm run dev

# MCP-specific debugging
MCP_DEBUG=1 npm start

# Node.js inspector
npm run inspect
# Then open chrome://inspect in Chrome

API Limits

• E2B Free Tier: 100 hours/month sandbox usage
• Concurrent Sandboxes: 5 active instances (Free), more on paid plans
• Timeout Limits: Default 10 minutes, configurable up to 24 hours

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines.

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass: npm test
6. Commit your changes: git commit -m 'Add amazing feature'
7. Push to the branch: git push origin feature/amazing-feature
8. Open a Pull Request

Code Style

• Use TypeScript for all new code
• Follow existing code formatting (Prettier)
• Add JSDoc comments for public APIs
• Include error handling and validation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• E2B Documentation
• Model Context Protocol
• E2B Desktop SDK
• Issue Tracker

🙏 Acknowledgments

• E2B for providing the cloud sandbox infrastructure
• Anthropic for the Model Context Protocol specification
• The open-source community for various tools and libraries used in this project

---