BrowserPilot Documentation

Quick Start

Follow these steps to install, verify, and connect BrowserPilot end to end.

Start with the install flow: Open the BrowserPilot install flow for the Chrome Web Store entry point, the runtime-helper sequence, and the BrowserPilot-owned recovery path.
Complete setup from your account: Sign into account.seedsource.dev, copy the BrowserPilot setup command from your account panel, and run it on the machine where BrowserPilot will live.
Check runtime status: Run browserpilot status. Expected: active device session and the local BrowserPilot bridge endpoint on port 9225.
Connect your MCP client: Use the SSE endpoint http://127.0.0.1:9225/sse.

In .vscode/mcp.json:

{
  "servers": {
    "browserpilot": {
      "type": "sse",
      "url": "http://127.0.0.1:9225/sse"
    }
  }
}

In your claude_desktop_config.json:

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

In MCP settings, add an SSE server pointing to http://127.0.0.1:9225/sse.

In MCP settings, add an SSE server pointing to http://127.0.0.1:9225/sse.

BrowserPilot provides 29 MCP tools. Each tool below lists its exact tool name, what it does, and key parameters.

browserpilot_navigate: Navigate active tab to a URL. Key params: url.
browserpilot_navigate_back: Go back in tab history. Key params: none.
browserpilot_navigate_forward: Go forward in tab history. Key params: none.
browserpilot_wait_for_navigation: Wait for navigation/load completion after click/submit. Key params: timeoutMs.

browserpilot_list_tabs: List all open Chrome tabs with control eligibility metadata. Key params: none.
browserpilot_get_active_tab: Get currently active tab details and control eligibility metadata. Key params: none.

browserpilot_click: Real CDP click with optional safe-mode override and dialog handling. Key params: selector, overrideToken, dialogPolicy.
browserpilot_double_click: Double-click with element metadata and locator hints. Key params: selector, overrideToken, dialogPolicy.
browserpilot_hover: Move cursor to an element without clicking. Key params: selector.
browserpilot_drag_and_drop: Drag source element to target element. Key params: sourceSelector, targetSelector.
browserpilot_press_key: Send keyboard input via CDP, with optional modifiers and targeted selector focus. Key params: key, selector, modifiers, code, keyCode.
browserpilot_scroll: Scroll by x/y offsets or scroll an element into view. Key params: x, y, selector.

browserpilot_type_text: Type into one field with native semantics and readback. Key params: selector, text, clearFirst, fieldGroup.
browserpilot_write_form: Fill multiple fields in order with per-field status and locator hints. Key params: fields, clearFirst, stopOnError.
browserpilot_select_option: Select an option in a select element by value, label, or index. Key params: selector, value, label, index.
browserpilot_file_upload: Upload one or many files to an input type file element. Key params: selector, files.
browserpilot_handle_dialog: Accept/dismiss alert-confirm-prompt dialogs. Key params: accept, promptText.
browserpilot_resolve_row_value_input: Find value input by row key text to avoid brittle selectors. Key params: keyText, rowSelector, keySelector, valueSelector.

browserpilot_snapshot: Return page model including headings, landmarks, interactives, focused element, page text, and locator hints. Key params: maxElements, compact, maxTextLength.
browserpilot_screenshot: Capture image/png screenshot of active tab. Key params: none.
browserpilot_evaluate: Run JavaScript expression in active tab and return result. Key params: code, overrideToken.
browserpilot_wait_for_element: Wait for DOM element to appear and return metadata/locator hints. Key params: selector, timeoutMs.
browserpilot_snapshot_diff: Semantic diff between snapshots. Key params: after, before, storeAfter.

browserpilot_create_slot: Create isolated browser tab slot context. Key params: slotName.
browserpilot_select_slot: Route subsequent actions to selected slot context. Key params: slotName.
browserpilot_list_slots: List slots and associated tabs. Key params: none.

browserpilot_set_device_metrics: Emulate mobile viewport/device metrics or reset desktop mode. Key params: width, height, deviceScaleFactor, mobile, reset.
browserpilot_get_optimizer_metrics: Read token optimizer session metrics when optimization is enabled. Key params: none.

browserpilot_ping: Verify extension-to-bridge reachability and liveness. Key params: none.

Local-first architecture: MCP clients communicate with your local bridge at 127.0.0.1.
No cloud DOM relay: page interactions and snapshots are handled locally, not routed through BrowserPilot servers.
Entitlement validation: activation verifies entitlement/device session without requiring your browsing data.
Safety controls: sensitive actions can require overrideToken in safe mode.

Check runtime status: run browserpilot status. Expected: active device session and local bridge endpoint on port 9225.
Revalidate setup: if browserpilot status looks wrong after setup or repair, rerun the setup command from your account panel to restore bridge and session state.
Test liveness from MCP: call browserpilot_ping. Expected: success response proving extension and bridge connectivity.
Cannot connect from client: confirm the client is using exact SSE URL http://127.0.0.1:9225/sse (no trailing path changes).
Extension not detected: reinstall from CWS, then rerun the setup command from account.seedsource.dev and confirm browserpilot status.
Port conflict: if port 9225 is busy, stop the conflicting process and rerun setup.