Zamery Browser

io.github.maemreyov0.1.2Updated Oct 6, 2026

Use your existing Firefox and logged-in tabs, limited to tabs or groups you explicitly share.

VerifiedSTDIODesktop onlySecurity & MonitoringBrowser Automation

Overview

AI-generated overview

Lets a local agent use your existing Firefox, with your logins, on only the tabs and tab groups you explicitly share.

What it does
A standalone MCP server that connects a local agent to the Firefox you already use, limited to tabs and groups you choose to share (R2). Tools cover connection and access status (browser_status, browser_request_access), shared tabs and snapshots (browser_contexts, browser_snapshot), synthetic DOM actions such as click, fill, type and key, handoff and claim control, mutation status lookup, and tab and group management (R29-R39). Snapshots expose controls but no form values or hidden controls, and every mutation carries a stable request_id (R33, R40). It does not expose raw JavaScript or eval, and the agent cannot grant itself access (R4).
When to use it
Use it when an assistant should work inside your real, logged-in Firefox session rather than a separate headless browser, for example to read or act on specific pages you deliberately share. It fits workflows where you want to grant access per tab or group, for a session or 1-30 days, and to take over control at any time (R20, R23). It is not meant for unattended automation of your whole browser, since access is always granted by you in Firefox (R18, R31).
Requirements
Runs locally over stdio as the npm package @zamery/browser-mcp, typically via npx (R1, R2). Requires the Firefox companion and the native host from @zamery/browser-firefox (R7), and a desktop Firefox with the tabs or groups you choose to share. Optional environment variables: ZAMERY_BROWSER_MCP_STATE_DIR, ZAMERY_BROWSER_MCP_CONSUMER_ID, ZAMERY_BROWSER_MCP_BROWSER_INSTANCE_ID, ZAMERY_BROWSER_MCP_PROVIDER (R44-R47). No authentication is declared.
Before you install
The agent can act on shared pages: clicks, fills, typing, keys, tab and group changes (R34, R38, R39), and mutations carry a request_id whose outcome may be outcome_unknown, so retrying with a new id is discouraged (R40, R41). Sign-in, one-time-code and payment fields are flagged CREDENTIAL and writes are refused (R27). The consumer id is a same-OS-user routing key, not an authenticated identity, and another process of the same user could talk to the bridge, though it still needs its own grant (

Installation

In SourceWeft

  1. Open Zamery Browser in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

@zamery/browser-mcp

A standalone MCP server that lets a local agent (for example Codex) use the Firefox you are already using — with your logins — on only the tabs and tab groups you choose to share.

text
agent host (stdio) → @zamery/browser-mcp → BrowserProvider V2 + optional interfaces  → @zamery/browser-firefox → Native Messaging host → Zamery Browser Companion → your Firefox

It does not depend on Pi or Zamery Workbench. It does not expose raw JavaScript/eval, and the agent cannot grant itself access.

Status: stable 0.1.2, released with Zamery Browser v0.2.3 and Mozilla-signed/public Companion 0.2.5. Clean published-artifact acceptance, signed real-profile acceptance and Official MCP Registry publication all pass.

Install

bash
codex mcp add zamery-firefox -- npx -y @zamery/browser-mcp@latest

You also need the Firefox companion and the native host from @zamery/browser-firefox (see its README).

Official MCP Registry: io.github.maemreyo/zamery-browser.

Codex recipe (needed for screenshots)

In a tested Codex setup the model did not receive inline MCP images, so it guessed what a screenshot showed. browser_screenshot therefore also returns a local image file path, and the model must open it with its image viewer. Add codex/AGENTS.snippet.md to your project's AGENTS.md (or install codex/skill/zamery-browser as a Codex skill). With it, a neutral visual question was answered correctly 3/3 against a real Firefox; without it, 0/2.

How access works

  1. The agent calls browser_status. It always works, even before Firefox is connected or anything is shared, and says what to ask you. If Firefox is connected but nothing is shared, the agent may call browser_request_access once to ask for your attention. The request contains no tab/group/action/duration choices and never grants anything.
  2. Firefox shows a toolbar badge and, if you enabled optional notifications, a generic OS notification. You open the Zamery Browser panel and choose the local agent, the tab(s) or group, what the agent may do, and for how long (this session, or 1–30 days).
  3. The agent calls browser_contexts / browser_snapshot. A snapshot with claim=true (default) takes the write claim; the returned short refs (e1, e2, …) can then be used with browser_click, browser_fill, browser_type, browser_key.
  4. You can take over at any time from the panel. In the default interactive mode, using the claimed page also hands control to you. With explicit Background control, ordinary use of the same shared page only invalidates the agent's old snapshot; it can take a fresh snapshot and continue. While explicit user control is active, the agent cannot act and can only ask you to resume.

Sign-in, one-time-code and payment fields are never filled by the agent: they are flagged CREDENTIAL in snapshots and writes are refused; use browser_handoff (request_user_takeover).

Tools

ToolPurpose
browser_statusConnection, access, expiry, who is in control, and what to do next.
browser_request_accessAsk Firefox to draw the user's attention before a grant exists. It never grants, widens, resumes or confirms access.
browser_contextsTabs shared with the agent.
browser_snapshotControls of a shared tab (no form values, no hidden controls) and, by default, the write claim.
browser_click / browser_fill / browser_type / browser_keySynthetic DOM actions (isTrusted=false). Need the claim and a fresh observation.
browser_handoffrequest_user_takeover, resume (a request only), claim, release.
browser_mutation_statusLook up what happened to an action by its request_id.
browser_tabCreate/navigate/reload/activate/close-own tabs (only what you allowed).
browser_groups, browser_groupRead and change Firefox tab groups you shared.

Every mutation carries a stable request_id. After a timeout or a lost response the outcome may be outcome_unknown: the agent must not retry with a new id; it checks browser_mutation_status and the page.

Configuration (environment)

VariableMeaning
ZAMERY_BROWSER_MCP_STATE_DIRWhere the stable consumer id is stored (default ~/Library/Application Support/Zamery/browser-mcp).
ZAMERY_BROWSER_MCP_CONSUMER_IDOverride the consumer id ([A-Za-z0-9._:-]{8,128}).
ZAMERY_BROWSER_MCP_BROWSER_INSTANCE_IDPin one Firefox profile when several are connected.
ZAMERY_BROWSER_MCP_PROVIDERProvider allowlist selector; only firefox exists. Arbitrary module paths are rejected.

The consumer id binds your grant to this installation, so restarting the MCP process or the agent keeps working under the same approval. It is a same-OS-user routing key, not an authenticated identity.

Trust boundary

The local Firefox bridge trusts the logged-in OS user. Another process of the same user could talk to the bridge, but still needs the grant you created in Firefox for its own consumer id. Page content (titles, URLs, control names) is untrusted data and is labelled as such in tool output.

License

Apache-2.0.

Source: packages/browser-mcp/README.md at commit 7db39b1

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.1.2LatestOct 6, 2026