EdgeBox MCP Server

How to use

Connect your MCP client to the local EdgeBox server and start issuing tasks to your AI agent. You can run code in isolated environments, manipulate files, and drive the on‑screen desktop to interact with apps and websites. EdgeBox supports multi‑session workspaces so you can run different tasks in parallel by assigning unique session identifiers. Use the MCP interface to send natural language instructions like requesting a Python script, creating files and folders, automating browser actions, or taking screenshots of the desktop.

How to install

Prerequisites: you must have Docker Desktop installed and running on your system.

Step 1: Download EdgeBox. Retrieve the latest release appropriate for your platform from the releases channel. Install the application for your operating system.

Step 2: Start Docker Desktop if it isn’t already running.

Step 3: Run EdgeBox locally. Use the platform‑specific launcher: on Windows run EdgeBox.exe, on macOS open EdgeBox.app, or on Linux run the AppImage or the package you installed.

Additional sections

Overview EdgeBox exposes its capabilities through the MCP protocol, providing three core modules: a full desktop environment (computer use), a complete code interpreter and shell, and seamless LLM agent integration. The HTTP MCP interface is the primary method for connecting your LLM client. You can create and manage multiple isolated sandbox sessions by providing an x‑session‑id header with your requests.

HTTP MCP configuration (example) sets up EdgeBox as an MCP server endpoint that your client can reach at the local address.

{
  "mcpServers": {
    "edgebox": {
      "url": "http://localhost:8888/mcp"
    }
  }
}

Multi‑Session Concurrency

EdgeBox supports running multiple sandbox sessions concurrently. When you want to isolate different tasks, assign a unique session identifier using the x-session-id header in each MCP request. This ensures separate file systems, processes, and GUI contexts for each task.

execute_python

Run Python code in an isolated, secure environment with a dedicated filesystem per session.

execute_typescript

Execute TypeScript/JavaScript code in a sandboxed runtime within EdgeBox.

execute_r

Run R code for statistical analysis inside an isolated environment.

execute_java

Execute Java code in a contained sandbox.

execute_bash

Run Bash scripts in a secure, isolated shell.

shell_run

Interact with the Linux shell in a persistent, stateful session.

shell_run_background

Execute commands in the background with process management.

fs_list

List directory contents within the sandbox filesystem.

fs_read

Read files from the sandbox filesystem.

fs_write

Create or modify files within the sandbox filesystem.

fs_info

Retrieve metadata and information about files and directories.

fs_watch

Monitor directory changes in real time.

desktop_mouse_click

Programmatically perform mouse clicks on GUI elements.

desktop_mouse_double_click

Perform double‑click actions on GUI elements.

desktop_mouse_move

Move the cursor to specific screen coordinates.

desktop_mouse_scroll

Scroll the mouse wheel with configurable delta.

desktop_mouse_drag

Drag from one position to another on the screen.

desktop_keyboard_type

Type text into focused fields with clipboard support for non‑ASCII characters.

desktop_keyboard_press

Simulate keyboard key presses like Enter, Escape, Tab, etc.

desktop_keyboard_combo

Execute key combinations (Ctrl+C, Alt+Tab, etc.).

desktop_get_windows

List currently open windows with titles and IDs.

desktop_switch_window

Focus a specific window by ID or title.

desktop_maximize_window

Maximize a chosen window.

desktop_minimize_window

Minimize a chosen window.

desktop_resize_window

Resize a window to specified dimensions.

desktop_screenshot

Capture a desktop screenshot in PNG format.

desktop_launch_app

Launch an application by name.

desktop_wait

Pause execution for a specified duration between actions.