haden-browser

haden-browser is a fast, AI-first web browser exposed as a local Model Context Protocol server. It gives an AI the smallest useful page representation for its current goal instead of sending screenshots and raw page source on every turn.

Benchmark: 33% less AI browser context

Primary result: Haden used 7,822 reference tokens for the core browsing session—32.7% fewer than Playwright MCP and 32.5% fewer than Chrome DevTools MCP full mode. Among the tested browser MCPs that returned semantic action refs and image-alt coverage, Haden had the lowest token footprint.

† Chrome Slim is the absolute token minimum, but it is a low-level JavaScript control baseline: the model must author page scripts, and the tested path returned no semantic action refs or image alt text. It is therefore shown transparently but is not treated as a semantic-browser equivalent.

Core context includes one complete tool-schema load plus the serialized MCP tool calls and results for article reading, form submission, and computed-style inspection. Counts use the o200k_base tokenizer. Image pixels, user/system prompts, and model reasoning or prose are excluded, so actual billed usage depends on the MCP host and model.

See the full benchmark report, raw per-run data, and reproduction instructions.

Related MCP server: browsegrab

Why it is different

• Goal-based views — use compact semantic text for research, sanitized DOM for structure, or bounded computed styles for visual work.

• Images stay lazy — an image is represented as its alt text or [image img1]. Pixel data is returned only when the AI explicitly calls haden_image.

• Low round-trip control — every interaction returns a fresh snapshot, so most click/type flows need one tool call per step.

• Stable action references — visible controls become e1, e2, and so on, which are cheaper and more reliable than asking a model to invent CSS selectors.

• Fast by default — image, media, and font requests are blocked during ordinary browsing. CSS remains available for the visual view.

• Safer local execution — non-HTTP schemes, credential-bearing URLs, and private-network targets are blocked unless the user explicitly opts in.

flowchart LR
    AI[AI / MCP host] -->|stdio tools| MCP[haden-browser]
    MCP --> PW[Playwright Chromium]
    PW --> PAGE[Web page]
    PAGE -->|semantic text / DOM / computed CSS| MCP
    MCP -.->|only haden_image imgN| PIXELS[Image bytes]
    PIXELS -.-> AI

Views

text is the default and should be preferred unless the task truly needs structure or presentation details.

MCP tools

Example text output:

# Example Domain
URL: https://example.com/
View: text
Interactive elements: 1
Images: 1 (use haden_image with an img ref only when visual inspection is needed)

# Example Domain
This domain is for use in illustrative examples.
[e1] link "More information" -> https://iana.org/domains/example
[image img1: "Example diagram"]

References are scoped to the latest snapshot. Read again after substantial page changes before reusing an old e or img ref.

Requirements

• Node.js 20 or newer

• Chromium installed through Playwright

Install from this repository

git clone https://github.com/Haden-Min/haden-browser.git
cd haden-browser
npm ci
npm run setup-browser
npm run build

Then configure an MCP host to launch the built stdio server. Use an absolute path in real configuration:

{
  "mcpServers": {
    "haden-browser": {
      "command": "node",
      "args": ["/absolute/path/to/haden-browser/dist/index.js"]
    }
  }
}

During development, a host can launch npx tsx /absolute/path/to/haden-browser/src/index.ts instead.

After the package is published to npm, the intended configuration is:

{
  "mcpServers": {
    "haden-browser": {
      "command": "npx",
      "args": ["-y", "haden-browser"]
    }
  }
}

Run npx playwright install chromium once on that machine before the first browser call.

Configuration

Boolean variables accept true/false, 1/0, yes/no, and on/off.

Local development pages

Private hosts are blocked by default to reduce SSRF risk. To browse an application on localhost, opt in for that MCP process only:

{
  "mcpServers": {
    "haden-browser-local": {
      "command": "node",
      "args": ["/absolute/path/to/haden-browser/dist/index.js"],
      "env": { "HADEN_ALLOW_PRIVATE_HOSTS": "true" }
    }
  }
}

Development

npm install
npm run setup-browser
npm run check
npm run build

The test suite covers network policy, text shaping, real Chromium extraction, ref-based interactions, lazy image retrieval, and an in-memory MCP client/server connection.

Current limitations

• One active browser context is maintained per stdio MCP connection.

• Image refs currently cover visible HTML <img> elements, not CSS background images, canvases, video frames, or iframe contents.

• The visual view reports computed properties; it does not dump every stylesheet rule.

• Downloads, file uploads, browser extensions, persistent profiles, and CAPTCHA solving are outside the MVP.

• Private-host filtering reduces SSRF exposure but is not a substitute for OS/container-level network isolation in hostile multi-tenant environments.

See CONTRIBUTING.md for development guidance and SECURITY.md for vulnerability reporting.

License

MIT