mcp-zen
Allows remote control of a Firefox (or Zen) browser, enabling navigation, clicking, form filling, screenshots, and JavaScript execution via a WebSocket connection to a browser extension.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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
npm install && npm run buildZen:
about:debugging→ This Firefox → Load Temporary Add-on →firefox-extension/manifest.jsonOptions page: Enable browser automation (
<all_urls>). Optional: Enable isolated sessions (Firefox containers for namedsessions).Temporary add-ons unload on browser restart unless you install permanently.
2. Ports (optional)
cd mcp-server
cp .env.example .envMCP_HTTP_PORT(default8791) — MCP clientsEXTENSION_PORT(default8765) — extension WebSocketMCP_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-zenPoint 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 |
|
|
| Navigate the currently selected tab; no browser launch flags |
| Live tab HTML; |
| A11y-style tree + |
|
|
|
|
| Chords like |
|
|
|
|
| Required |
|
|
| Path + image content; |
| Requires |
| Currently selected tab |
| Page-realm JS |
|
|
| |
| Owned tabs/containers only — not your browser |
| Iframes (Stripe/PayPal/3DS) |
| Click/fill by role, text, label, testid, … |
| Substring, glob, or |
| |
| |
|
|
| |
| Synthetic touch |
|
|
Reliable targeting
Use
@eNfrom snapshots; bareeNis 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_finddefaults to click. Useaction: "text"to read without activating the match. Snapshot queries do not click.evalmay 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. Preferzen_browser_media_*on CSP-strict video pages instead ofeval.zen_browser_locatenever clicks;zen_browser_findstill 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 testAdapter 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.jsregenerates 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 clientLicense
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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Stealth web browser for agents: search, fetch, click, download and type in persistent MCP sessions.
Hosted real Google Chrome MCP with per-user persistent state. Navigate, click, type, screenshot.
Unofficial Browserless MCP — wraps the Browserless headless-Chromium REST API (browserless.io)
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceEnables MCP clients to control a real local browser window for web automation tasks such as clicking, typing, scrolling, and taking screenshots.184 npm-
- AlicenseAqualityCmaintenanceBrowser 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.2219 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseNot gradedqualityBmaintenanceEnables agents to control a browser over HTTP MCP to open pages, take screenshots, click coordinates, and record audio/video as WebM.MIT