e2b-sandbox-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

An MCP (Model Context Protocol) server that gives Claude Code access to E2B cloud sandboxes — isolated Linux VMs for cloning repos, running commands, managing files, and performing git operations without touching the local machine. Communicates over stdio transport.

Build & Run

npm run build          # TypeScript → dist/
npm run dev            # Build + run
npm start              # Run from dist/ (must build first)

No test suite or linter is configured.

Register as MCP Server

claude mcp add e2b-sandbox -s user \
  -e E2B_API_KEY=your-key \
  -e GITHUB_TOKEN=your-token \
  -- node /absolute/path/to/dist/index.js

Environment Variables

• E2B_API_KEY (required) — from e2b.dev/dashboard. Without it, sandbox_create fails immediately.
• GITHUB_TOKEN (optional) — enables private repo cloning and git push. Auto-configured on sandbox creation via sandbox.git.dangerouslyAuthenticate().

Architecture

Single-process MCP server, ESM ("type": "module"), strict TypeScript targeting ES2022/Node16.

Entry point: src/index.ts — creates McpServer, registers all tool groups, connects via StdioServerTransport.

Singleton sandbox registry: src/services/sandbox-manager.ts — SandboxManager class holds a Map<sandboxId, {sandbox, info}> of live E2B Sandbox instances. All tools look up sandboxes by ID through this registry. Stale sandbox detection happens in commands.ts (catches "not found" errors, removes from registry).

Tool registration pattern: Each file in src/tools/ exports a register*Tools(server: McpServer) function that calls server.tool() with Zod schemas for input validation. Four tool groups (29 tools total):

• sandbox.ts — lifecycle (create, list, info, kill, keep_alive, pause, resume) + networking (get_url, upload_url, download_url)
• commands.ts — exec, exec_background (with output truncation at 100KB per stream), process_list, process_kill
• filesystem.ts — read, write, list (capped at 1000 entries), mkdir, remove, info, exists, rename
• git.ts — clone (shallow depth=1 by default), status, commit, push, pull, branch, init