@seleniumbox/sbox-mcp

Model Context Protocol (MCP) server for Selenium Box (SBOX). Exposes SBOX APIs to AI-assisted IDEs (Cursor, Windsurf, IntelliJ) as MCP tools. Runs locally on your machine via npx—no Docker required.

Installation

No install step. Your IDE runs the server via npx (same pattern as TestingBot MCP):

npx -y @seleniumbox/sbox-mcp@latest

IDE configuration

Cursor / Windsurf

Add to your MCP settings (e.g. .cursor/mcp.json or Cursor Settings → MCP):

{
  "mcpServers": {
    "sbox": {
      "command": "npx",
      "args": ["-y", "@seleniumbox/sbox-mcp@latest"],
      "env": {
        "SBOX_API": "http://localhost:4444"
      }
    }
  }
}

• SBOX_API – Base URL of your SBOX hub (no trailing slash). Default: http://localhost:4444.

Then restart Cursor or reload MCP.

Required environment variables

| Variable | Default | Description | |------------|---------------------------|--------------------------------------| | SBOX_API | http://localhost:4444 | Base URL of the SBOX hub (no slash). |

Optional:

| Variable | Default | Description | |-------------------------|-------------|-----------------------------------------------------------------------------| | MCP_DEBUG or DEBUG | — | Set to 1 or true to log incoming MCP and outbound SBOX API request/response (sensitive fields redacted). | | MCP_REQUEST_TIMEOUT_MS| 30000 | Timeout for outbound SBOX API requests. | | SBOX_MCP_TOKEN_FILE | see below | Override path for the persisted session token file (default: ~/.sbox-mcp/token). | | SBOX_ALLOW_INSECURE_SSL | (default: skip verification) | Set to 0 or false to verify TLS certificates; unset or 1/true skips verification (default). |

Token cache

After you log in via sbox_open_login, the session token is stored in memory and on disk so it survives MCP process restarts (e.g. when the IDE starts a new process per prompt). Default location: ~/.sbox-mcp/token. The cache directory is created with mode 0700 and the token file with 0600. Set SBOX_MCP_TOKEN_FILE to use a different path (only the token file; the directory is inferred for last_poll_id). If an API call returns 401 or “invalid token”, the cache is cleared so the next run will prompt for login again.

Authentication flow

1. User asks the AI to log in to SBOX (e.g. “authenticate with SBOX”).
2. The sbox_open_login tool runs:
   • Checks that the MCP add-on is enabled on the hub.
   • Generates a unique session id, opens the login URL in your default browser (or returns auth_url so the IDE can open it).
3. You sign in on the SBOX hub (local, LDAP, or OIDC).
4. The hub stores the token by session id; MCP polls for it and caches it.
5. Subsequent SBOX tools use the cached token automatically.

Device + Poll: No callback server on your machine. The hub holds the token and MCP retrieves it by polling. Same contract as before; only distribution is local.

SBOX_API usage

• All MCP tools that call the hub use SBOX_API (or SBOX_API_BASE_URL) to build URLs, e.g. {SBOX_API}/e34/api/....
• The login URL shown to you is {SBOX_API}/ui/login?poll_id=.... Use the same base URL in your browser as the hub (e.g. http://localhost:4444 for a local hub).

Playwright on SBOX (MCP)

• Use sbox_list_playwright_versions to discover available Playwright versions.
• Use sbox_get_playwright_ws_endpoint to build a ws:// / wss:// endpoint for browserType.connect().
• The endpoint is built from SBOX_API and includes the current auth token automatically.
• Supported browser paths: chrome, chromium, firefox, webkit, msedge.

Typical flow in an MCP client:

1. Authenticate with sbox_open_login / sbox_complete_login.
2. Call sbox_get_playwright_ws_endpoint with browser_name (+ optional playwright_version, project_name, video, etc.).
3. Use returned wsEndpoint with Playwright connect():

import { chromium } from "playwright";

const browser = await chromium.connect(wsEndpointFromMcpTool);
const page = await browser.newPage();
await page.goto("https://example.com");
await browser.close();

Hub requirements

• MCP add-on enabled (license flag E34_MCP).

License

Apache-2.0