browser-mcp-lite

Drive a real Chrome from an AI agent over the Model Context Protocol — with no browser extension, no native messaging, and zero npm dependencies.

The browser is launched headless, driven through the Chrome DevTools Protocol, and torn down when the session ends. If Chrome is not installed the tools say so; if it is, nothing needs to be installed into your browser profile.

npx browser-mcp-lite doctor      # check Node, Chrome and the auth token
npx browser-mcp-lite audit https://example.com --widths=390,768,1440

Why this exists

Most browser MCP servers need a companion extension. That means the model can only see the browser a human has already set up, permissions live in chrome://extensions, and the whole thing breaks the moment the profile moves. Driving CDP directly removes the extension from the equation and makes the browser a disposable process instead of a shared, stateful one.

It also ships the two audits that manual screenshotting keeps failing to catch:

• horizontal overflow — finds the element that pushes the page wider than the viewport and names it with a CSS selector

• WCAG AA contrast — walks every text node, composites translucent and layered backgrounds, and reports the measured ratio

Both are available as MCP tools (audit_page) and as a CLI that exits non-zero, so they work in CI.

Related MCP server: OpenBrowser

Requirements

Install

npm install -g browser-mcp-lite      # CLI on your PATH
npm install browser-mcp-lite         # or as a project dependency

Nothing else. There is no lockfile-sized dependency tree because there are no dependencies.

Wire it into an MCP client

opencode

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "browser": {
      "type": "local",
      "command": ["npx", "-y", "browser-mcp-lite", "mcp"],
      "enabled": true
    }
  }
}

Claude Code / Claude Desktop

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

VS Code (.vscode/mcp.json)

{
  "servers": {
    "browser": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "browser-mcp-lite", "mcp"]
    }
  }
}

HTTP bridge

Some clients cannot spawn a process. The bridge speaks the same JSON-RPC over HTTP (and SSE) on loopback, guarded by a bearer token:

bml bridge
# listening on http://127.0.0.1:12307/mcp
# bearer token: 9f1c…

curl http://127.0.0.1:12307/mcp \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The token is generated on first run and stored at ~/.browser-mcp-secrets.json with 0600 permissions (or ~/.browser-mcp-secrets.token). loadToken() from browser-mcp-lite/server/token.js returns it for clients that need to authenticate themselves. GET /health is open and lists the tools without touching the browser.

The bridge binds to 127.0.0.1 and refuses requests without a valid token. BML_INSECURE=1 disables the check for local debugging only.

Tools

read_page is the important one. It returns landmarks, headings, links and controls as a compact outline instead of a wall of HTML, and stamps each node with a ref:

url: https://example.com
title: "Example"
lang: pt-BR
viewport: 1440x900

- ref=r1 | role=banner | label="Example"
- ref=r2 | role=navigation | label="Main"
  - ref=r3 | role=link | label="Docs" | href=/docs
- ref=r4 | role=searchbox | label="Search" | placeholder=Search
- ref=r5 | role=button | label="Enviar"

Refs are re-generated on every read_page, so always re-read after navigating. label is the computed accessible name; everything after it is the raw attribute.

CLI

bml doctor                                    # environment check
bml tools                                     # the tool catalogue as JSON
bml shot https://example.com out.png --full --color-scheme=dark
bml audit https://example.com --widths=390,768,1440 --json=report.json

bml audit prints one line per URL × width and exits 1 on any failure, which makes it a CI step:

- run: npx browser-mcp-lite audit https://example.com --widths=390,768,1440

--continue-on-fail keeps the exit code at 0 when you only want the report. Nodes sitting on a background image or gradient are reported as needsManualReview rather than guessed at — a numeric ratio would be a lie there.

Environment variables

Development

npm test                # unit + protocol tests
BML_E2E=1 npm test      # also boots Chrome and drives a fixture page

The unit tests cover colour maths, token handling and the JSON-RPC surface. The integration tests launch a real browser and assert the behaviour you actually depend on: refs resolve, clicks fire, input events reach framework listeners, screenshots are valid images, and both audits catch a page that is deliberately broken.

Limitations

• Chromium-based browsers only. No WebKit, no Gecko.

• Headless by default; a headed session is available but not useful for interactive login flows.

• No network interception, request mocking or cookie management.

• Contrast is computed from computed styles, so text composited over a canvas or an image is flagged for manual review rather than measured.

License

MIT