runloop-mcp

A FastMCP server that exposes Runloop Devbox operations as Model Context Protocol (MCP) tools. It uses the official runloop-api-client Python SDK and lets AI agents (Claude, Cursor, etc.) create and manage isolated Linux sandboxes, run commands, edit files, snapshot disks, and drive interactive PTY sessions.

Features

Related MCP server: mcp-devtools

Requirements

• Python 3.10+

• A Runloop API key — get one at app.runloop.ai

Installation

# Clone
git clone https://github.com/contributory/runloop-mcp.git
cd runloop-mcp

# (Optional) virtual environment
python -m venv .venv && source .venv/bin/activate

# Install
pip install -e .

# Set your API key
export RUNLOOP_API_KEY=your_runloop_api_key_here

Usage

stdio transport (default, for local MCP clients)

runloop-mcp
# or
python -m runloop_mcp

HTTP/SSE transport (for remote MCP clients)

runloop-mcp --transport http --host 0.0.0.0 --port 8000

Running from Python

from runloop_mcp import mcp

if __name__ == "__main__":
    mcp.run(transport="stdio")

Connecting from an MCP client

Configure Claude Desktop / Cursor with the command, e.g.:

{
  "mcpServers": {
    "runloop": {
      "command": "runloop-mcp",
      "env": { "RUNLOOP_API_KEY": "your_runloop_api_key_here" }
    }
  }
}

Examples

The tools mirror the Runloop SDK. Some examples:

# Create a devbox
create_devbox(
    name="my-agent-box",
    blueprint_name="runloop/universal-ubuntu-24.04-x86_64",
    resource_size="SMALL",
)

# List running devboxes
list_devboxes(status="running")

# Execute a command (blocking)
execute_command(devbox_id="dev_...", command="python3 --version")

# Write a file
write_file(devbox_id="dev_...", file_path="/home/user/app.py", contents="print('hi')")

# Snapshot the disk
create_snapshot(devbox_id="dev_...", name="before-refactor")

# Suspend / resume
suspend_devbox(devbox_id="dev_...")
resume_devbox(devbox_id="dev_...")

# Interactive PTY
pty_send_command(session_name="repl", command="python3 -i", max_wait=30.0)

See examples/example.py for a complete walkthrough.

Tools reference

Devbox lifecycle

• create_devbox — create a devbox with optional blueprint, snapshot, env vars, file mounts, launch commands, instance size, architecture, TTL, and idle lifecycle policy.

• list_devboxes — list devboxes, optionally filtered by status.

• get_devbox — retrieve a single devbox by id.

• update_devbox — update a devbox's name and/or metadata.

• suspend_devbox — suspend a devbox (disk state preserved).

• resume_devbox — resume a suspended devbox.

• shutdown_devbox — shut down / delete a devbox.

Execution & files

• execute_command — run a command and block until completion, returning stdout, stderr, exit_status. Optional shell_name gives you a stateful named shell.

• execute_command_async — start a command and return immediately with an execution_id (use for long-running servers/watchers).

• write_file — create or overwrite a file on a devbox.

• read_file — read a file's contents from a devbox.

Snapshots

• create_snapshot — snapshot a devbox's disk (synchronous).

• list_snapshots — list disk snapshots, optionally filtered by devbox.

PTY sessions

• pty_connect — create or reconnect to an interactive PTY session; returns the WebSocket connect_url.

• pty_send_command — send a command through the PTY WebSocket and capture output (for TTY-aware programs, REPLs, TUIs).

• pty_control — resize the terminal, deliver a POSIX signal, or close the session.

Notes & gotchas

• Prefer execute_command for normal, non-interactive commands; PTY is heavier and intended for true interactive use.

• Each execute_command spawns an isolated shell unless you reuse a shell_name.

• Background processes started in launch_commands must redirect output (> /tmp/out.log 2>&1 &) or the devbox will never become active.

• Only one WebSocket client may attach to a PTY session at a time.

• Snapshots and suspended devboxes accrue storage charges until deleted/shut down.

License

MIT