BrowserForge MCP

Give your AI agent a real browser, and turn the traffic it sees into API docs and clients.

A local-first Firefox + Chrome extension and MCP server for Claude Code, OpenAI Codex and any other MCP client.

Why BrowserForge

Related MCP server: byob

Quick start

Requires Node.js 22 or newer, and Chrome, Edge, Brave or Firefox, on Linux, macOS or Windows (Linux is the one it has been tested on; see docs/INSTALL.md).

# From npm (no build): npm install -g browserforge-mcp   then:   browserforge setup
# From a checkout:
npm install && npm run build
node apps/mcp-server/dist/cli.js serve     # prints endpoints, creates tokens in ~/.config/browserforge/
node apps/mcp-server/dist/cli.js tokens    # shows the extension token

1. Load the extension.

   • Firefox: about:debugging#/runtime/this-firefox → Load Temporary Add-on → apps/firefox-extension/dist/firefox/manifest.json

   • Chrome: chrome://extensions → Developer mode → Load unpacked → apps/firefox-extension/dist/chrome

2. Connect it. Click the toolbar icon, paste the extension token, press Connect.

3. Connect your agent. Guides: Codex · Claude Code

   codex mcp add browserforge --url http://127.0.0.1:7345/mcp --bearer-token-env-var BROWSERFORGE_MCP_TOKEN
   claude mcp add --transport http browserforge http://127.0.0.1:7345/mcp --header "Authorization: Bearer $(cat ~/.config/browserforge/mcp-token)"

4. Try it. Start the demo site with node tests/fixtures/demo-site/server.mjs, then ask your agent:

   Call system_status, then open http://127.0.0.1:8099/apply and describe the form.

Full instructions: docs/INSTALL.md. Problems: docs/TROUBLESHOOTING.md.

Things you can ask your agent

• "Open this site, click through the checkout flow, and tell me which API calls it makes."

• "Analyze the captured traffic and generate an OpenAPI spec and a Python client for the endpoints I used."

• "Fill in the application form from my saved profile, show me a preview, and wait for my approval before submitting."

• "Export the capture as a HAR file with secrets redacted."

More end-to-end examples: docs/WORKFLOWS.md.

Tools

Read-only tools carry readOnlyHint. Every tool has a strict JSON schema (unknown arguments are rejected) and bounded output.

browser_run_goal is an optional fast path: local models pick one routine step at a time from a compact table of the page. By default Qwen (via Ollama) decides; --decider cascade puts Laya (via Ollaya) first with Qwen as backup. The run hands back to your agent when the models are unsure, and every step says which model decided. It only types values you pass in, never navigates to other sites, and goes through the same approval gate as every other action.

Analysis and code generation themselves are deterministic and use no LLM.

Every site becomes a flow

BrowserForge records what an agent does on each website as a flow: steps, several ways to find each element, and your typed values as named parameters (passwords are never kept). Replay a flow with no model (flow_run), or export it as a script for Playwright (TypeScript, Python), Selenium (Python, Java), Chrome DevTools Recorder / Puppeteer Replay, or neutral JSON:

browserforge flow list
browserforge flow export <id> --format playwright-ts --out signup.ts
FLOW_CONFIRM=1 FLOW_PARAM_FIRST_NAME=Grace npx tsx signup.ts

Exported scripts stop before submits, sends and uploads unless you say FLOW_CONFIRM=1, since outside BrowserForge there is no approval prompt. Details: docs/FLOWS.md.

An agent window, and tables as data

• Agent window: turn it on in the popup and the agent works in its own window instead of the tabs you are using; it can still use one of yours when it selects it on purpose. Take over stops the agent and shows its window so you can finish by hand; Hand back lets it carry on. Details: docs/AGENT_WINDOW.md.

• Tables: browser_extract_table reads HTML tables and ARIA grids (also inside iframes) as column names and rows, with merged cells expanded, as JSON or CSV (spreadsheet formulas neutralised), or saved to a file so a big table does not fill the agent's context.

Memory that carries over

• Site cards: navigating to a site returns what is known about it (obstacles, past results, flows to replay); agents add to it with site_note. See docs/SITES.md.

• Automatic checks: after a submit, and at the end of browser_run_goal, the page is read for a confirmation or an error, and the run is labelled good or bad without waiting for anyone. browser_verify does it on demand.

• Flows to skills: flow_consolidate merges many recordings of a task into one clean flow, and flow_to_skill turns it into a shareable skill that replays with no model.

• Record me: an opt-in popup switch that also records your own clicks and fields as a flow and as training examples for the local model. Off by default, passwords never recorded, everything stays on your computer.

Extend BrowserForge: plugins and skills

Anyone can add to BrowserForge without touching the core:

• Skills: a folder with a SKILL.md (and optional ready-made workflows). No code; agents read it. browserforge skill new my-skill. docs/SKILLS.md

• Plugins: a small ES module that adds tools, with a manifest of exactly which folders, programs and browser access it needs. You see that list in plain words and approve it before it is installed; a later version asking for more is switched off until you approve again. browserforge plugin new my-tool. docs/PLUGINS.md

browserforge plugin search cv            # npm packages tagged "browserforge-plugin"
browserforge plugin add ./plugins/rendercv
browserforge plugin config rendercv cvDir=~/cv rendercv=~/venv/bin/rendercv

The first plugin is plugins/rendercv: tailor a RenderCV resume to each job (reorder and reword only; it rejects any number, link or tool name not already in your CV), render it, and keep an application log. Its companion skill skills/job-apply is a worked example of a skill. Contributing: CONTRIBUTING.md.

How it works

 Claude Code / Codex  ──MCP (HTTP + Bearer)──►  browserforge daemon  ──WebSocket (token + Origin)──►  extension in Firefox / Chrome
                                                 MCP tools · BrowserHub                                 background · content script · popup
                                                 NetworkStore · analyzer · generator                    approvals · STOP

1. A tool call is validated against its schema, then sent to the extension with a request id, timeout and cancellation.

2. The extension re-validates it, resolves the tab and element, and runs it in the page.

3. If the action looks consequential, it returns to the human for approval inside the browser before anything happens.

4. Results flow back to the agent as redacted, bounded, untrusted data.

Deeper dive: docs/ARCHITECTURE.md · docs/BROWSER_PROTOCOL.md · docs/RESEARCH.md.

Safety model

• Page content is data, never instructions. It is wrapped as untrusted before the agent sees it.

• Approvals live in the browser. The agent cannot answer the popup.

• Secrets are redacted from what the agent sees, from exports and from generated code. Revealing them requires starting the daemon with --allow-reveal.

• Nothing is persisted unless you export it. Captured traffic stays in memory.

• No anti-bot evasion and no arbitrary-JavaScript tool. CAPTCHA solving exists only as the opt-in browser_solve_captcha (local CapSkip app, needs --capskip and YOLO mode; see SECURITY.md).

Repository layout

apps/firefox-extension     cross-browser extension source (builds dist/firefox and dist/chrome)
apps/mcp-server            daemon: MCP (HTTP/stdio), extension WebSocket hub, tools, CLI
packages/browser-protocol  versioned Zod message and action schemas
packages/network-inspector capture store, filters, redacted views, HAR
packages/api-analyzer      traffic to endpoints, schemas, pagination, auth, evidence
packages/client-generator  OpenAPI 3.1, Python/TS/JS/PHP clients, safe writer, validators
packages/knowledge         local reference documents (BM25) and run traces
packages/flows             flow format, builder and exporters (Playwright, Selenium, Chrome Recorder, JSON)
packages/plugin-sdk        what plugin authors import: manifest, permission-checked api, test helper
plugins/                   reference plugins (rendercv)
skills/                    reference skills (job-apply)
packages/shared            errors, limits, redaction, path safety, tokens, logger
tests/                     unit · security · integration · e2e (real browsers) · demo site
docs/  examples/  CONTRIBUTING.md

Development

Status and limitations

Pre-release (0.1.0). BrowserForge reports what a WebExtension can actually see; it does not capture all browser traffic. For example, Firefox cannot observe WebSocket frames, content scripts run in the top frame only, and consequential-action detection is heuristic.

Read docs/LIMITATIONS.md for the full list and docs/RELEASE_CHECKLIST.md for the manual checks still required before a release.

Responsible use

Use BrowserForge only on sites and accounts you are authorised to automate or inspect, and respect their terms of service and the law. It is built for your own sessions and for legitimate testing, integration and documentation work.

License

MIT. See LICENSE and NOTICE.