@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
- 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.
- 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).
- 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.
- 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).
| Tool | Purpose |
|---|
browser_status | Connection, access, expiry, who is in control, and what to do next. |
browser_request_access | Ask Firefox to draw the user's attention before a grant exists. It never grants, widens, resumes or confirms access. |
browser_contexts | Tabs shared with the agent. |
browser_snapshot | Controls of a shared tab (no form values, no hidden controls) and, by default, the write claim. |
browser_click / browser_fill / browser_type / browser_key | Synthetic DOM actions (isTrusted=false). Need the claim and a fresh observation. |
browser_handoff | request_user_takeover, resume (a request only), claim, release. |
browser_mutation_status | Look up what happened to an action by its request_id. |
browser_tab | Create/navigate/reload/activate/close-own tabs (only what you allowed). |
browser_groups, browser_group | Read 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)
| Variable | Meaning |
|---|
ZAMERY_BROWSER_MCP_STATE_DIR | Where the stable consumer id is stored (default ~/Library/Application Support/Zamery/browser-mcp). |
ZAMERY_BROWSER_MCP_CONSUMER_ID | Override the consumer id ([A-Za-z0-9._:-]{8,128}). |
ZAMERY_BROWSER_MCP_BROWSER_INSTANCE_ID | Pin one Firefox profile when several are connected. |
ZAMERY_BROWSER_MCP_PROVIDER | Provider 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.