Skip to main content
Glama

mcp-zen

A persistent MCP HTTP server paired with a Zen/Firefox extension that lets any MCP client remote-control your already-running browser.

The public tool surface is zen_browser_*: one prefix for core browsing, frames, and additive media/locate tools. Schemas were captured from agent-browser 0.36.0 (pinned in common/agent-browser/) then renamed. The backend is your attached Firefox/Zen window, not a managed Chromium process. See docs/parity.md.

The server is one long-lived process. The extension's WebSocket stays up independently of short-lived MCP client sessions.

Setup

1. Load the extension in Zen

  1. npm install && npm run build

  2. Zen: about:debugging → This Firefox → Load Temporary Add-on → firefox-extension/manifest.json

  3. Options page: Enable browser automation (<all_urls>). Optional: Enable isolated sessions (Firefox containers for named sessions).

  4. Temporary add-ons unload on browser restart unless you install permanently.

2. Ports (optional)

cd mcp-server
cp .env.example .env
  • MCP_HTTP_PORT (default 8791) — MCP clients

  • EXTENSION_PORT (default 8765) — extension WebSocket

  • MCP_SCREENSHOT_DIR — screenshot files (server filesystem)

Localhost only. The extension origin is required on the WebSocket; browser origins are rejected on /mcp.

3. Run

bin/ is gitignored. Create the wrapper once per checkout:

mkdir -p bin
cat > bin/mcp-zen <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
exec node "$SCRIPT_DIR/../mcp-server/server.js" "$@"
EOF
chmod +x bin/mcp-zen
ln -sf "$(pwd)/bin/mcp-zen" ~/.local/bin/mcp-zen
mcp-zen

Point an MCP client at http://localhost:8791/mcp.

node mcpcall.mjs zen_browser_tab_list '{}'
node mcpcall.mjs zen_browser_open '{"url":"https://example.com"}'
node mcpcall.mjs zen_browser_snapshot '{}'
node mcpcall.mjs zen_browser_click '{"selector":"@e1"}'

Related MCP server: Web Bridge

Tools

Default profile is agent-browser core (29 tools). Every tool accepts the upstream common options; unsupported ones (allowedDomains, restore*, extraArgs, caCert, …) return UNSUPPORTED_CAPABILITY instead of being ignored.

Tool

Notes

zen_browser_tools_profiles

core only in this version

zen_browser_open

Navigate the currently selected tab; no browser launch flags

zen_browser_read

Live tab HTML; url navigates first if needed. llms fetches llms.txt

zen_browser_snapshot

A11y-style tree + @eN refs

zen_browser_click

@ref, bare eN, or first CSS match; newTab opens the link

zen_browser_fill / type

text (not value); synthetic input

zen_browser_press

Chords like Control+a; untrusted events

zen_browser_check / uncheck / select

select takes values: string[]

zen_browser_scroll

up|down|left|right, default 300px

zen_browser_wait_ms

Required ms ≥ 0

zen_browser_wait_for_selector / _text / _load

waitTimeoutMs; no networkidle

zen_browser_screenshot

Path + image content; fullPage / selector / annotate

zen_browser_get_text

Requires selector

zen_browser_get_url / get_title

Currently selected tab

zen_browser_eval

Page-realm JS

zen_browser_tab_new / tab_list / tab_switch / tab_close

tN / label / firefox:<id>

zen_browser_back / forward / reload

zen_browser_close

Owned tabs/containers only — not your browser

zen_browser_frame_switch / frame_main

Iframes (Stripe/PayPal/3DS)

zen_browser_find

Click/fill by role, text, label, testid, …

zen_browser_wait_for_url

Substring, glob, or /regex/

zen_browser_hover / scroll_into_view

zen_browser_get_value / get_attr / is_visible / is_enabled / is_checked

zen_browser_dialog_*

alert/confirm/prompt hooked after the runtime is installed

zen_browser_window_new

zen_browser_tap / swipe

Synthetic touch

zen_browser_console

{ clear?: boolean } — page console buffer

Reliable targeting

  • Use @eN from snapshots; bare eN is also accepted. Repeated snapshots retain refs for the same connected DOM node. Removed/replaced nodes, navigation, or evicted refs require a fresh snapshot; refs never automatically retarget.

  • Selectors use standard CSS (first match), xpath=..., or snapshot refs—not Playwright :has-text() / :text(). Scope to the intended post/player rather than using a page-wide [role=slider] (which can also match volume).

  • zen_browser_find defaults to click. Use action: "text" to read without activating the match. Snapshot queries do not click.

  • eval may be blocked by a site's CSP. Ordinary DOM tools still work.

  • Hover is synthetic and may not reveal CSS-only controls. A click response confirms dispatch, not application success: verify playback/seek state.

  • MCP clients must forward screenshot image content, not just its filesystem path. An image placeholder is not visual evidence.

  • Additive zen_* tools (locate, reveal, click_at, set_range, media_*) are Firefox capabilities, not agent-browser. Prefer zen_browser_media_* on CSP-strict video pages instead of eval. zen_browser_locate never clicks; zen_browser_find still defaults to click.

Follow the operator's active tab

Every page tool operates in the selected tab of the last-focused normal browser window. No remembered background-tab binding is used. tab_list reports actual browser active flags, browser windowId, and current for the selected tab in that window. Duplicate titles do not affect tab identity. If an older extension cannot disambiguate multiple browser windows, the server asks for the update.

To work elsewhere, explicitly call tab_switch: it selects the tab and focuses its browser window. New tabs/windows are visibly selected before navigation. tab_close cannot close a background tab; switch first. Bulk close visibly selects each owned tab before closing it and never closes personal tabs.

Manual tab changes are steering. Subsequent calls follow the newly selected tab and prefix a warning describing the change. Read-only waits can resume in the new tab within the original deadline. Old-tab element refs return a successful contextChanged result with fresh targets rather than clicking an unrelated control. Partially delivered input is never replayed: the response says previousAction: "possibly_partial" and supplies fresh context to continue. Concurrent sessions serialize against this single visible browser.

The extension rechecks selection before dispatch and capture; page waits and per-character typing check visibility between steps. Already-dispatched page JS, navigation, or input cannot be undone, and arbitrary eval scripts can schedule work outside the lifetime of a tool call. This policy controls tool dispatch; it is not a sandbox for arbitrary page JavaScript.

Omit session for personal tabs. Named sessions retain Firefox container isolation: select a tab in that container before operating there. A switch out of the named container does not silently transfer its work into a different cookie context.

For the permanent local installation, build then install the updated XPI through about:addons → gear → Install Add-on From File. The stable Gecko ID preserves the existing installation and permissions. Restart/reconnect MCP clients after restarting the server so they reload its instructions.

Optional animated agent cursor

If a listener exists at $XDG_RUNTIME_DIR/agent-cursor.sock, Zen notifies it before clicks, find mutations, typing, dropdown changes and hover/reveal. It waits up to 1800 ms for animation, revalidates the element, then performs the existing DOM operation exactly once. No listener means ordinary operation without animation. There is no import or runtime dependency on mcp-computer-use.

The companion listener is shipped by mcp-computer-use as agent-cursor.service. Both tools share the same renderer. AGENT_CURSOR_SOCKET overrides the endpoint; AGENT_CURSOR=off disables Zen's notifications. The server-side notifier speaks version 1 newline-delimited JSON, using desktop device pixels resolved internally. It cannot execute input. The model never supplies notification coordinates.

Extension 0.1.2 adds internal preparation tokens for checking element identity, position and hit testing after the arrow moves. Old extensions continue without animation. Typing highlights the arrow amber; the listener clears it on completion or a safety timeout. Unresponsive listeners are bounded and fail open.

To run the automated suite without drawing on your desktop: AGENT_CURSOR=off npm test. Cursor protocol tests use isolated temporary sockets.

Development

Plain ES modules, Node 22+. No TypeScript.

npm test
  • Adapter tests use a mock extension.

  • DOM tests use Chromium (CHROMIUM_PATH, default /usr/bin/chromium).

  • Live tests use a disposable Zen/Firefox profile (FIREFOX_PATH) and never attach to your daily browser.

  • node scripts/capture-agent-browser.js regenerates pinned schemas from a built agent-browser binary.

Project layout

common/agent-browser/   pinned upstream MCP schemas + provenance
mcp-server/             HTTP MCP server, adapter, read pipeline
firefox-extension/      background client + in-page runtime
docs/parity.md          core vs remaining 156-tool surface
test/                   schema, adapter, DOM, live Firefox
mcpcall.mjs             one-shot Streamable HTTP client

License

MIT — see LICENSE.

Pinned agent-browser schema JSON is copied from an Apache-2.0 project; see common/agent-browser/LICENSE.

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

    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to control a real local browser window for web automation tasks such as clicking, typing, scrolling, and taking screenshots.
      184 npm
      -
    • A
      license
      A
      quality
      C
      maintenance
      Browser automation MCP server that uses a real browser to give agents eyes and hands—open pages, click, fill, screenshot, and run scripts via accessibility-tree snapshots.
      22
      19 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to control live Zen Browser and Firefox tabs via MCP, performing actions like navigation, clicking, typing, scrolling, and running JavaScript through a local WebSocket bridge.
      MIT