E2b Sandbox MCP
MCP server: E2b Sandbox MCP
Installation
npx e2b-sandbox-mcpAsk AI about E2b Sandbox MCP
Powered by Claude ยท Grounded in docs
I know everything about E2b Sandbox MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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:
- Visit E2B Dashboard
- Sign up/log in
- Navigate to "API Keys"
- 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 onaction: 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 JavaScriptnpm run dev- Start development server with hot reloadnpm start- Start production servernpm run inspect- Start with Node.js debuggernpm test- Run test scriptsnpm run setup- Setup and test installation
Adding New Features
- New Computer Actions: Add to
src/computer-use-tools.ts - Enhanced Management: Modify
src/sandbox-manager.ts - API Extensions: Update
src/index.tswith 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
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes
- Add tests for new functionality
- Ensure all tests pass:
npm test - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - 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
๐ 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
โญ Star this repo if you find it useful!
Made with โค๏ธ for the AI automation community
