zen-browser
Lets Claude observe and drive real Firefox-based browser tabs (works with Zen, Firefox Developer Edition, Nightly, and ESR): listing and switching tabs, navigating, clicking, typing, scrolling, filling forms, reading accessibility-style page trees and page text, taking screenshots, and reading console output and network requests via an in-browser extension.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@zen-browser switch to the GitHub tab, open my latest PR, and summarize the review comments"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This is an unofficial community project. It is not made by, affiliated with, or endorsed by Anthropic.
About
Anthropic's Claude in Chrome extension only works in Chromium browsers. Zen is built on Firefox, so this project rebuilds the same idea for Firefox-based browsers. A small extension runs inside Zen, a local bridge connects it to Claude Code, and Claude Code gets a set of zen-browser tools that work on the tabs you're already signed in to.
Related MCP server: Kamurafox
Features
Full browser control. Open and switch tabs, navigate, click, type, press keys, scroll, hover, and fill forms. It works with React and Vue apps and inside shadow DOM.
Sees the page the way Claude needs it. It gives Claude an accessibility-style page tree with element references, a text search, readable page text, and screenshots that are scaled so the click coordinates line up.
Developer tools. It can run JavaScript in the page and read console output and network requests.
You can see what it's doing. While Claude works in a tab, the tab glows, a cursor dot shows each action, and a Stop button pauses Claude right away.
Live activity popup. The popup shows your connected Claude Code sessions and every action as it happens, and has a single switch that pauses everything.
Several sessions at once. Each Claude Code session gets its own connection, and all of them share the same browser.
Locked down. Everything stays on your machine. The extension and the bridge both have to prove they hold your private pairing key before either side will trust the other.
Getting started
Prerequisites
Zen browser. It also works in Firefox Developer Edition, Nightly, or ESR (see Limitations).
Node.js 18 or newer
Installation
1. Install the bridge and connect it to Claude Code
git clone https://github.com/grapedjuice/claude-for-zen.git
cd claude-for-zen
npm install
npm run setupnpm run setup registers the zen-browser MCP server with Claude Code for every project. It also prints your pairing key, which you'll need in step 3.
Want it in one project only? Runnpm run setup -- --no-register, then in that project run the claude mcp add --scope local … command it prints.
2. Install the extension in Zen
The extension isn't on the Mozilla add-ons store, so Zen has to be told to accept it:
Open
about:configin Zen, accept the warning, and setxpinstall.signatures.requiredtofalse.Download claude-for-zen.xpi from the latest release.
Open
about:addons, click the gear icon, choose Install Add-on From File…, and pick the downloaded.xpi.Optional: right-click the toolbar, choose Customize Toolbar, and pin the ✷ button.
3. Pair them
Click the ✷ button in Zen, paste the pairing key from step 1, and click Pair. To see the key again, run npm run pair in the claude-for-zen folder.
4. Restart Claude Code
Open a new Claude Code session. The popup should say Connected to 1 Claude Code session.
Updating
cd claude-for-zen
git pull
npm installThen download the latest .xpi and install it over the old one. Your pairing carries over.
Uninstalling
claude mcp remove --scope user zen-browserRemove the extension from about:addons, delete the claude-for-zen folder, and delete ~/.claude-for-zen (which holds the pairing key). If you want signature checks back on, set xpinstall.signatures.required to true again.
Usage
Ask Claude Code to do things in the browser in plain language:
> open my GitHub notifications in Zen and summarize what needs my attention
> fill out the sign-up form on localhost:3000 with test data and tell me what breaks
> check the console on the current tab for errors and find the cause in this repo
> compare the prices on these three open tabsClaude starts by listing your tabs, then reads pages and acts on elements by reference. It takes screenshots when the layout matters.
Pause or stop. Click Stop on the in-page bar, or turn off the switch in the popup. Claude gets a clear "paused" error until you turn it back on.
Choose the tab. Claude acts on whatever tab you tell it to. If you don't name one, it uses the active tab in the focused window.
Tools
Tool | What it does |
| List tabs (id, title, URL, active). Tabs in other Zen workspaces are flagged. |
| Open, focus, and close tabs. |
| Go to a URL, or |
| Capture the visible tab as an image. |
|
|
| Accessibility-style tree. Interactive elements are tagged |
| Find elements by role, name, or text. |
| Set text fields, selects, checkboxes, radios, and contenteditables by |
| Readable text of the page. |
| Run JavaScript and return the last expression. Top-level |
| Console output and uncaught errors for a tab. |
| Requests the tab made since it loaded. |
| Resize the browser window. |
How it works
Claude Code ──MCP over stdio──▶ bridge (server/index.js) ◀──WebSocket on 127.0.0.1:47321–47330──▶ Zen extension ──▶ your tabsThe bridge. Claude Code starts one bridge per session. Each bridge takes the first free port between 47321 and 47330.
The extension. It checks those ports, connects to every bridge it finds, and carries out the tool calls.
Why not native messaging? Chrome extensions normally talk to Claude through native messaging. Here, the bridge is the process Claude Code launches, so a localhost socket with mutual authentication is simpler and works the same way on Windows, macOS, and Linux.
Security
Mutual authentication. The bridge and the extension each prove they hold the pairing key with an HMAC-SHA256 challenge–response that uses fresh nonces in both directions. The extension ignores commands from any bridge that can't prove the key. The bridge drops any extension that can't, within 5 seconds. Other extensions, other local programs, and other users on the same machine can't pose as either side.
The key stays private. It lives in
~/.claude-for-zen/pairing-key, inside your user profile.Websites can't reach it. The bridge listens on
127.0.0.1only. It accepts WebSocket connections only frommoz-extension://origins with a loopbackHostheader, which blocks DNS-rebinding tricks. Its HTTP probe returns only{bridge, version}.Page scripts can't change settings. Pairing and settings can only be changed from the popup. Code running in the page, including code from the
javascripttool, can only press Stop.Passwords are masked.
read_pageshows password fields as••••.Nothing leaves your machine except through Claude Code. The extension only talks to localhost. What Claude reads is sent to Anthropic through Claude Code, as with any other tool output.
Page content is untrusted. A web page can contain text written to manipulate an AI (prompt injection). Claude is told to treat page content as data, not instructions. Still, keep an eye on what it does on sites you don't trust, and use Stop if anything looks off.
Limitations
Synthesized input. Firefox has no
chrome.debuggerAPI, so clicks and keys are generated inside the page and haveevent.isTrusted = false. Most sites don't care, but some captchas and anti-bot checks ignore this kind of input.Native dropdowns.
<select>dropdowns can't be opened by clicking. Claude usesform_inputfor them instead.Iframes. The extension only works in a page's top-level frame, so it can't type into fields inside iframes.
Browser pages.
about:pages and addons.mozilla.org are off-limits to all extensions.Console capture. Capture starts while a Claude Code session is connected. For tabs that were opened before that, reload the tab to capture its logs.
Firefox release builds. Regular Firefox ignores
xpinstall.signatures.required. In release Firefox, load the extension temporarily fromabout:debugging(it's removed when the browser restarts), or use Developer Edition, Nightly, or ESR.
Troubleshooting
Restart Claude Code after running
npm run setup.Run
claude mcp listand check thatzen-browsershows Connected.Make sure nothing else is using all of ports 47321–47330.
Run npm run pair in the claude-for-zen folder and paste the key into the popup. If you deleted ~/.claude-for-zen, a new key was created and you need to pair again.
xpinstall.signatures.required is still true. Set it to false in about:config and try again.
The browser can't capture a minimized window. Claude brings the window forward and tries again, but if Zen stays minimized the capture fails.
npm run setup registers the bridge for every project, so each open Claude Code session connects. To limit it to certain projects, see the tip in Installation.
Development
extension/ Firefox WebExtension (Manifest V2)
background.js connections, pairing, tool dispatch, screenshots, network log
content.js page reading, synthetic input, in-page overlay
console-hook.js console capture, registered only while a session is connected
popup/ toolbar popup
server/index.js MCP server + localhost WebSocket bridge
scripts/setup.mjs one-time setup (register + pair)npm install
npm run lint # web-ext lint
npm run build # writes dist/claude-for-zen.xpiTo try local changes, load extension/manifest.json from about:debugging#/runtime/this-firefox → Load Temporary Add-on.
Contributing
Issues and pull requests are welcome.
Fork the repo and create a branch:
git checkout -b fix/somethingMake your change, run
npm run lint, and try it in Zen.Commit and open a pull request that describes what changed and how you tested it.
License
Distributed under the MIT License. See LICENSE for details.
Available Tools
15 toolscomputerB
Mouse and keyboard actions in a tab. Click actions take either a coordinate (from the latest screenshot) or a ref. Actions: left_click, right_click, double_click, triple_click, hover, type (text into the focused element), key (space-separated keys like "Enter", "ctrl+a", "Backspace Backspace"), scroll, scroll_to (ref), wait, screenshot, zoom (region of the screenshot at higher detail).
Inputs: action (required), ref, text, tabId, +5 more.
findB
Find elements whose role, accessible name or text contains the query (case-insensitive). Returns up to 20 refs.
Inputs: query (required), tabId.
form_inputB
Set the value of an input, textarea, select, checkbox/radio or contenteditable element by ref.
Inputs: ref (required), value (required), tabId.
get_page_textC
Extract the readable text of the page (main/article content first).
Inputs: tabId, max_chars.
javascriptA
Run JavaScript in the tab and return the value of the last expression (top-level await works). Runs in the extension's isolated world with full DOM access; reach page globals via window.wrappedJSObject. Return JSON-able values. For debugging and inspection, not for faking user input.
Inputs: code (required), tabId.
read_console_messagesC
Read console output (log/info/warn/error/debug and uncaught errors) captured from the tab.
Inputs: clear, limit, tabId, pattern, +1 more.
read_network_requestsB
List network requests made by the tab since the extension started watching it.
Inputs: limit, tabId, urlPattern.
read_pageA
Read the page as an accessibility-style tree. Interactive elements are tagged [ref_N] for use with computer/form_input.
Inputs: tabId, filter, ref_id, max_chars.
resize_windowC
Resize the Zen window containing the tab.
Inputs: width (required), height (required), tabId.
screenshotB
Capture the visible part of a tab as an image. The tab is brought to the front first.
Inputs: tabId.
tabs_closeC
Close a tab.
Inputs: tabId (required).
tabs_contextA
List the tabs in the focused Zen window (tabId, title, URL, which is active). Call this first to get tab ids.
Inputs: all_windows.
tabs_createB
Open a new tab (optionally at a URL) and make it active. Returns its tabId.
Inputs: url.
tabs_selectC
Switch to (activate) a tab.
Inputs: tabId (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Most tools target clearly distinct actions: tab lifecycle (tabs_*), navigation, page reading, element finding, form input, JS eval, console/network reading. The main overlaps are the standalone screenshot tool versus computer's built-in 'screenshot'/'zoom' actions, and read_page vs get_page_text vs find, which require reading descriptions to separate. These are minor and descriptions do disambiguate, but an agent could still occasionally reach for the wrong page-reading tool.
The tabs_* group is consistent but uses noun_verb order (tabs_create, tabs_close) while other tools use verb_noun (get_page_text, read_page, resize_window) or bare nouns/verbs (screenshot, navigate, computer, javascript, find). It's readable and mostly self-explanatory, but two conflicting conventions coexist with no unifying scheme.
15 tools is well within a healthy range for a browser-automation server, and each tool maps to a meaningful capability (tab management, interaction, inspection, diagnostics). Nothing feels redundant enough to cut, and no obvious gap-forcing consolidation is needed.
The surface covers the full browser workflow: tab lifecycle, navigation with history, screenshots, DOM reading, element search, form filling, JS execution, console and network diagnostics, and window resizing. Minor gaps exist—no drag-and-drop action in computer, no cookie/localStorage or download management, and no explicit reload—but agents can work around these via javascript or navigate.
Maintenance
Related MCP Connectors
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Hosted browser for agents: open pages, search the web, extract data, read PDFs and take screenshots.
Give AI agents a real cloud Chrome: open sessions, navigate, read pages, click, type and screenshot.
Let your AI agent operate any website through a real, logged-in browser session.
Related MCP Servers
- AlicenseBqualityCmaintenanceLets Claude Code attach to a running, signed-in Firefox over WebDriver BiDi to control tabs, navigate, screenshot, read pages, click, type, fill forms, evaluate JavaScript, and inspect console/network activity.22MIT
- AlicenseNot gradedqualityBmaintenanceEnables Claude Code to drive a local Firefox browser: opening and managing tabs, navigating, reading page structure and text, clicking, typing, filling forms, running JavaScript, taking screenshots, and inspecting console messages and network requests. Everything runs over a local Unix socket with no network traffic, and actions are restricted to tabs explicitly placed under Claude's control.4 npmGPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables Claude Code to control Firefox through tools for tabs, navigation, clicks, typing, scrolling, screenshots, page reading, forms, JavaScript, and console/network logs.MIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude Code to control the user's real Firefox browser through a local MCP server, with tools for tabs, navigation, page reading, clicking, typing, forms, screenshots, and file uploads under per-site consent.MIT