Zamery Browser

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

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

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

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)

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.