OpenSandbox MCP Server for Claude Code and Cursor

The OpenSandbox MCP server wraps the OpenSandbox Python SDK as a set of MCP tools, making every sandbox operation — creating and killing sandboxes, running commands, reading and writing files — directly available to MCP-capable AI clients such as Claude Code and Cursor. Once connected, agents can provision isolated sandbox environments, write and execute code, inspect outputs, expose ports, and clean up, all without leaving the chat or editor interface.

Installation

Install the opensandbox-mcp package from PyPI:

pip install opensandbox-mcp

Start the server (defaults to stdio transport):

opensandbox-mcp

Configuration

Environment Variables

Set these before starting the server or inject them through your client’s MCP configuration:

Variable	Description
`OPEN_SANDBOX_API_KEY`	API key for authenticating with the OpenSandbox server.
`OPEN_SANDBOX_DOMAIN`	Server domain (e.g. `localhost:8080` or `api.opensandbox.io`).

CLI Flags

All configuration can also be passed as flags, which take precedence over environment variables:

opensandbox-mcp --api-key <key> --domain <domain> --protocol http

Flag	Description
`--api-key`	OpenSandbox API key.
`--domain`	OpenSandbox API domain.
`--protocol`	`http` or `https` (default: `http`).
`--request-timeout-seconds`	HTTP request timeout in seconds (default: `30`).
`--transport`	Transport mode: `stdio` (default) or `streamable-http`.

Client Integrations

Claude Code — stdio
Claude Code — HTTP
Cursor — stdio
Cursor — HTTP

claude mcp add opensandbox-sandbox --transport stdio -- \
  opensandbox-mcp --api-key "$OPEN_SANDBOX_API_KEY" --domain "$OPEN_SANDBOX_DOMAIN"

If you are running the server in streamable-HTTP mode (see below), connect Claude Code to the running instance:

claude mcp add opensandbox-sandbox --transport http http://localhost:8000/mcp

Add the following block to your Cursor MCP configuration file (.cursor/mcp.json in the project, or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "opensandbox-sandbox": {
      "command": "opensandbox-mcp",
      "args": [
        "--api-key",
        "${OPEN_SANDBOX_API_KEY}",
        "--domain",
        "${OPEN_SANDBOX_DOMAIN}"
      ]
    }
  }
}

If the server is already running in streamable-HTTP mode, point Cursor at the URL instead of launching a process:

{
  "mcpServers": {
    "opensandbox-sandbox": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Available MCP Tools

All tools that operate on an existing sandbox require a sandbox_id. Obtain one from sandbox_create or sandbox_connect. The file_read and file_write tools are text-only; use the encoding and range_header parameters for large files.

Sandbox Lifecycle

Tool	Description
`sandbox_create`	Create a new sandbox and register it locally. Returns the `sandbox_id`.
`sandbox_connect`	Attach to an existing sandbox by ID and register it locally.
`sandbox_kill`	Terminate a sandbox by ID.
`sandbox_get_info`	Fetch full sandbox info (image, state, metadata) by ID.
`sandbox_list`	List sandboxes with an optional `filter` object.
`sandbox_renew`	Extend the sandbox expiration time.
`sandbox_healthcheck`	Check whether the sandbox is healthy and ready.
`sandbox_get_metrics`	Retrieve current resource usage metrics.
`sandbox_get_endpoint`	Get the public network endpoint URL for a given port.

Command Execution

Tool	Description
`command_run`	Run a shell command inside the sandbox and return output.
`command_interrupt`	Interrupt a running command.

Filesystem

Tool	Description
`file_read`	Read a text file from the sandbox.
`file_write`	Write a text file to the sandbox.
`file_delete`	Delete one or more files.
`file_search`	Search for files by glob pattern.
`file_create_directories`	Create one or more directories.
`file_delete_directories`	Delete one or more directories.
`file_move`	Move or rename a file or directory.
`file_replace_contents`	Replace the contents of an existing file.

Typical Workflow

Create a sandbox

Call sandbox_create with the desired image (e.g. python:3.12). Save the returned sandbox_id — every subsequent tool call needs it.

Write code or assets

Use file_write to place source files, configuration, or data into the sandbox filesystem before execution.

Run a command

Call command_run to execute scripts, install dependencies, run tests, or start a service. Output is returned in the tool response.

Expose a port (if needed)

If the command started a server, call sandbox_get_endpoint with the port number to get the public URL.

Clean up

Call sandbox_kill to terminate the sandbox and release its resources.

Streamable HTTP Transport

By default, opensandbox-mcp uses stdio and is launched as a subprocess by the MCP client. For scenarios where you want a shared, long-running server process — or where your client does not support subprocess management — start the server in streamable-http mode instead:

opensandbox-mcp --transport streamable-http

The server starts on port 8000 and exposes the MCP endpoint at http://localhost:8000/mcp. Any MCP client that supports HTTP transport can then connect to it.

HTTP transport is useful when multiple agents or editor windows need to share the same MCP server process, or when running the server on a remote host.

Get Started

SDKs

CLI & MCP

Guides

Deployment

Architecture

OpenSandbox MCP Server for Claude Code and Cursor

Installation

Configuration

Environment Variables

CLI Flags

Client Integrations

Available MCP Tools

Sandbox Lifecycle

Command Execution

Filesystem

Typical Workflow

Streamable HTTP Transport

Build docs developers (and LLMs) love

Get Started

SDKs

CLI & MCP

Guides

Deployment

Architecture

Documentation Index

​Installation

​Configuration

​Environment Variables

​CLI Flags

​Client Integrations

​Available MCP Tools

​Sandbox Lifecycle

​Command Execution

​Filesystem

​Typical Workflow

​Streamable HTTP Transport

Build docs developers (and LLMs) love

Installation

Configuration

Environment Variables

CLI Flags

Client Integrations

Available MCP Tools

Sandbox Lifecycle

Command Execution

Filesystem

Typical Workflow

Streamable HTTP Transport