@jiweiyuan/runbrowser-mcp

Standalone MCP (Model Context Protocol) server for RunBrowser — control your running Chrome browser via Playwright with your logins, extensions, and cookies already there.

Setup

Prerequisites

1. Install the RunBrowser Extension from Chrome Web Store
2. Click the extension icon on a tab → turns green when connected

MCP Client Configuration

Add to your MCP client settings (e.g., Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "runbrowser": {
      "command": "npx",
      "args": ["-y", "@jiweiyuan/runbrowser-mcp@latest"]
    }
  }
}

MCP Tools

The server exposes the following tools:

| Tool | Description | |------|-------------| | execute | Run Playwright code snippets with {page, state, context} in scope | | reset | Recreate CDP connection and reset browser/page/context | | snapshot | Take accessibility snapshot of the current page (fast, text-based) | | screenshot | Take screenshot with Vimium-style accessibility labels overlaid |

MCP Resources

| Resource | Description | |----------|-------------| | debugger-api | Debugger API documentation | | editor-api | Live editor API documentation | | styles-api | CSS styles inspection API documentation |

Environment Variables

RUNBROWSER_AUTO_ENABLE

Auto-create a tab when Playwright connects (no manual extension click needed).

{
  "mcpServers": {
    "runbrowser": {
      "command": "npx",
      "args": ["-y", "@jiweiyuan/runbrowser-mcp@latest"],
      "env": {
        "RUNBROWSER_AUTO_ENABLE": "1"
      }
    }
  }
}

Remote Agents (Devcontainers, VMs, SSH)

Run agents in isolated environments while controlling Chrome on your host.

On host (where Chrome runs):

npx -y @jiweiyuan/runbrowser serve --token <secret>

In container/VM (where agent runs):

{
  "mcpServers": {
    "runbrowser": {
      "command": "npx",
      "args": ["-y", "@jiweiyuan/runbrowser-mcp@latest", "--host", "host.docker.internal", "--token", "<secret>"]
    }
  }
}

Or with environment variables:

{
  "mcpServers": {
    "runbrowser": {
      "command": "npx",
      "args": ["-y", "@jiweiyuan/runbrowser-mcp@latest"],
      "env": {
        "RUNBROWSER_HOST": "host.docker.internal",
        "RUNBROWSER_TOKEN": "<secret>"
      }
    }
  }
}

Use host.docker.internal for devcontainers, or your host's IP for VMs/SSH.

Programmatic Usage

import { startMcp } from '@jiweiyuan/runbrowser-mcp'

// Start MCP server (connects to stdio transport)
await startMcp()

// With remote relay server
await startMcp({
  host: 'host.docker.internal',
  token: 'your-secret-token',
})

License

MIT