Cbrowser

What cbrowser does

cbrowser connects AI agents to browser automation and website evaluation workflows. It can control pages, collect page content, inspect browser state, and run audits that measure how difficult a site may be for particular users or agent workflows.

The project includes an MCP server, a command-line interface, and a library. The MCP interface exposes the same broad tool set as the hosted server: 130 tools, plus seven tools available only from the local server. Its focus extends beyond basic browser control into cognitive UX testing, agent-readiness analysis, accessibility-oriented persona testing, visual checks, and failure discovery.

A cognitive transport chain evaluates eight aspects of an experience: visual complexity, cognitive load, decision difficulty, motor demands, motor procedure, frustration, readability, and reading attention. These measurements are used to estimate where a persona may abandon a task.

How it works

Run the local MCP endpoint with npx cbrowser mcp-server. Browser actions operate against websites through the installed browser runtime. Installing the npm package downloads Chromium; if installation scripts were skipped, Chromium can be installed separately with npx playwright install chromium.

The CLI also provides direct commands such as agent-ready-audit, empathy-audit, and cognitive-journey. Audits can produce HTML reports, while --json-output, --plain, and --no-color support scripts and screen readers. A simulated journey can use a named persona, starting URL, and goal to model a visitor attempting a task.

Most direct browser operations and audits are keyless. Model-driven journeys and comparisons require an Anthropic API key because each step uses a model call. The ask command can answer questions about cbrowser documentation without an account or API key, subject to rate limits.

Setup and configuration

Use Node.js 20.9 or newer, then install the package globally:

npm install -g cbrowser
cbrowser doctor

Start the MCP server locally with:

npx cbrowser mcp-server

Set an Anthropic key for cognitive journeys with cbrowser config set-api-key <key>. The CLI supports configuration for viewport dimensions, locale, timezone, device, and geographic settings. The default viewport is 1920 by 1080; mobile, tablet, and desktop presets are also available.

Tools and capabilities

• Navigate, click, fill, type, scroll, take screenshots, extract content, and evaluate scripts.
• Run agent-readiness, empathy, accessibility, visual, responsive, performance, cross-browser, and AI-focused audits.
• Execute cognitive journeys using built-in personas, compare personas, and benchmark competing sites.
• Create and repair test suites, check for flaky behavior, hunt bugs, and run chaos testing.
• Inspect network requests, HAR data, console output, cookies, and browser captures.
• Use visual overlays and attention analysis, with HTML or JSON-oriented output for reporting and automation.

Limitations and notes

Cognitive journeys, explore, persona comparisons, competitive benchmarks, and empathy audits that include a goal require an Anthropic API key. Replaying a saved journey trace is free. The local MCP server uses stdio transport, and its red-zone safety refusals for actions such as clicks, typing, dragging, key presses, and script evaluation return tool errors with guidance on how to run the action.

Commands fail with a nonzero exit status when operations fail, including unsuccessful navigation or clicks through the daemon. One-off device and geographic settings do not carry over to later commands. The browser uses the host locale and timezone unless these are configured explicitly.