Skip to main content
Glama

NOTE

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

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 setup

npm 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.

TIP

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:

  1. Open about:config in Zen, accept the warning, and set xpinstall.signatures.required to false.

  2. Download claude-for-zen.xpi from the latest release.

  3. Open about:addons, click the gear icon, choose Install Add-on From File…, and pick the downloaded .xpi.

  4. 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 install

Then download the latest .xpi and install it over the old one. Your pairing carries over.

Uninstalling

claude mcp remove --scope user zen-browser

Remove 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 tabs

Claude 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

tabs_context

List tabs (id, title, URL, active). Tabs in other Zen workspaces are flagged.

tabs_create · tabs_select · tabs_close

Open, focus, and close tabs.

navigate

Go to a URL, or back / forward, and wait for the page to load.

screenshot

Capture the visible tab as an image.

computer

left_click, right_click, double_click, triple_click, hover, type, key, scroll, scroll_to, wait, screenshot, zoom. Targets elements by ref or by coordinate.

read_page

Accessibility-style tree. Interactive elements are tagged [ref_N].

find

Find elements by role, name, or text.

form_input

Set text fields, selects, checkboxes, radios, and contenteditables by ref.

get_page_text

Readable text of the page.

javascript

Run JavaScript and return the last expression. Top-level await works.

read_console_messages

Console output and uncaught errors for a tab.

read_network_requests

Requests the tab made since it loaded.

resize_window

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 tabs
  • The 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.1 only. It accepts WebSocket connections only from moz-extension:// origins with a loopback Host header, 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 javascript tool, can only press Stop.

  • Passwords are masked. read_page shows 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.debugger API, so clicks and keys are generated inside the page and have event.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 uses form_input for 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 from about: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 list and check that zen-browser shows 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.xpi

To try local changes, load extension/manifest.json from about:debugging#/runtime/this-firefox → Load Temporary Add-on.

Contributing

Issues and pull requests are welcome.

  1. Fork the repo and create a branch: git checkout -b fix/something

  2. Make your change, run npm run lint, and try it in Zen.

  3. 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 tools
computerB

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

    B3.2/5.0

    Scored across 15 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Lets 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.
      22
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      GPL 3.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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