Skip to main content
Glama

browser-control

A Firefox extension drives your visible, logged-in browser, and a small bridge exposes that browser as an MCP server for agents. The agent works in its own tab — one you can watch — with your logins, your cookies and your profile. No headless browser, no second profile, no automated login.

Agent  ──MCP over HTTP──▶  Bridge (Node)  ──WebSocket──▶  Firefox extension
        (bearer token)     127.0.0.1:8111                  agent tab

The extension dials out to the bridge. That is why the bridge needs no inbound port, and why the agent can only see tabs it created itself.

What it does

Thirteen tools, all with the browser_ prefix:

Tool

Purpose

status

windows and tabs as JSON, agent tabs marked

navigate, read

open a page (waits for it to settle), read its content as text

click, type, focus

interact, type, bring the tab to the front

inspect

query the DOM, selector and attributes

open_tab, close_tab

manage agent tabs (at most five)

eval

run code in the page context (off by default)

screenshot

the visible part of the tab (off by default)

frames

list and address iframes

transcript

a YouTube transcript as segments with timestamps, in the video's original track

Plus: settle detection instead of fixed sleeps, shadow DOM and frames, persistence across a background tab, and a log that does not copy page text.

Related MCP server: firefox-bridge

Security

  • One token, kept on the operator's filesystem and never in the repo; the bridge checks it on every MCP request.

  • Loopback only. The MCP port is bound to 127.0.0.1 and does not belong behind a public proxy.

  • Three switches, all off by default: password fields, code evaluation, screenshots. The agent never flips them itself.

  • The agent only sees its own tabs. It does not drive yours.

Quick start

The full guide is INSTALL.md: token file, bridge as a systemd user service, loading the extension. A reverse proxy is optional and covered at the end.

Short version for one machine without a proxy:

# 1. server side: token file, systemd user unit, service start — one command
cd ~/browser-control
./scripts/install.sh

# 2. extension: about:debugging#/runtime/this-firefox → "Load Temporary Add-on…"
#    → pick extension/manifest.json, then paste the token under Preferences.
#      The endpoint is pre-filled with ws://127.0.0.1:8110.

./scripts/install.sh --dry-run shows what the first step would do without writing anything. The manual equivalent — openssl rand -hex 32 for the token, cp of the unit plus systemctl --user enable --now — is in INSTALL.md sections 2 and 3, for when you want to see or change a single step.

The extension is unsigned. After a Firefox restart it is gone and has to be loaded again; signing through AMO is not set up.

Development

There are no dependencies — Node ≥ 22 is enough:

npm test        # 757 cases, TAP output, ~95 s
npm run check   # node --check over every .js/.mjs

How changes happen (spec → gate → dev plan → review → acceptance) is described in CONTRIBUTING.md; the design and measurement history lives in docs/ — 34 specs, each with its measurements and the decisions that followed.

Known limits

  • Unsigned: temporary load, again after every Firefox restart.

  • Windows is only partly covered (docs/29, docs/30).

  • YouTube labels can lie: browser_transcript reads the track YouTube calls the original; language detection is deliberately out of scope.

  • One operator, one browser: the bridge serves the extension that is connected.

License

MIT.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Drive Firefox-based browsers (Floorp, LibreWolf, Zen, Waterfox, Mullvad, Firefox) from any MCP client — read pages, screenshot, click, fill forms and manage tabs in your real session, over Marionette/WebDriver. OS input & JS eval locked by default.
      41
      71 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP-capable CLIs to operate real, already-logged-in Firefox tabs via a WebExtension and native messaging, without simulated input. Supports navigation, clicking, typing, reading, screenshots, and console/network capture with policy gating and frame awareness.
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables an MCP client to drive a real, already-logged-in Firefox session through a WebExtension rather than a WebDriver connection, so tabs, cookies and logins work as-is without relaunching the browser under remote-control flags. Exposes tools for tab listing and selection, navigation, accessibility-style snapshots, clicking, filling, typing, key presses, file uploads, screenshots and waiting, with per-origin permission grants and opt-in script evaluation.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables an MCP client such as Claude Code to read and operate your real, everyday Firefox profile — reading pages, clicking, typing, navigating, switching tabs and taking screenshots — with per-action human approval and masking of password, one-time-code and credit card fields.
      MIT