chromex

Chromex

Zero-dependency Chrome DevTools Protocol toolkit for AI agents. 56 typed MCP tools + CLI. Connects directly to Chrome, Brave, Edge, or Chromium via WebSocket. No Puppeteer, no bloat.

Features

• 56 MCP tools -- typed JSON Schema, annotations (readOnlyHint, destructiveHint), inline screenshots (base64)
• Zero dependencies -- uses only Node.js 22+ built-in modules (WebSocket, fs, net, crypto)
• Ref-based selection -- snap --refs assigns @e1, @e2... to interactive elements, then click @e5 or fill @e3 "value". No fragile CSS selectors
• Incremental snapshots -- second snapshot returns only changed nodes (diff), reducing output from thousands of lines to just what changed
• Auto-snapshot -- interactive commands (click, fill, nav, etc.) automatically append an incremental snapshot with refs, so the agent sees the page state in a single round-trip
• Scroll detection -- snapshots report scrollable containers with remaining distance ([scroll: page: down:1200px | sidebar: up:300px])
• Per-tab persistent daemons -- each tab gets a background process connected via Unix socket. Chrome's "Allow debugging" modal fires once, not on every command
• Security hardened -- domain filtering (allow/blocklist), CDP method blocklist, token-authenticated sockets, full audit log
• Multi-browser -- auto-detects Brave, Chrome, Chrome Canary, Chromium, Edge, Vivaldi (macOS + Linux)
• Network control -- throttle to 3G/offline, intercept & mock requests, record HAR files
• Form filling -- fill inputs, select dropdowns, toggle checkboxes, upload files, batch fill entire forms. Works with React/Vue/Angular
• Browser launcher -- launch browser with remote debugging pre-enabled (skips the "Allow debugging" modal entirely)
• CLI included -- same commands available from the terminal for scripts and CI/CD

Requirements

• Node.js 22+ (for built-in WebSocket)
• Any Chromium-based browser

Installation

# Add to Claude Code (global -- all projects)
claude mcp add chromex -s user npx chromex-mcp@latest

# Or project-only
claude mcp add chromex npx chromex-mcp@latest

Auto-Approve (recommended)

Add to ~/.claude/settings.json:

{
  "permissions": {
    "allow": ["mcp__chromex"]
  }
}

This approves all 56 MCP tools at once. For granular control, approve individual tools:

{
  "permissions": {
    "allow": [
      "mcp__chromex__chromex_list",
      "mcp__chromex__chromex_snapshot",
      "mcp__chromex__chromex_screenshot",
      "mcp__chromex__chromex_perf"
    ]
  }
}

Global install (optional)

npm install -g chromex-mcp

This installs three binaries:

Binary	Purpose
chromex	CLI -- the main command for terminal usage
chromex-cli	Alias for chromex
chromex-mcp	MCP server (stdio JSON-RPC) -- used by claude mcp add, not run directly

chromex list                          # List open tabs
chromex launch --url https://example.com  # Launch browser
chromex snap 6BE8 --refs              # Snapshot with refs
chromex click 6BE8 @e3               # Click by ref

Connect to Your Browser

Option A: Launch a new browser (recommended -- no setup needed)

chromex launch --url https://example.com

This starts Chrome/Brave/Edge with remote debugging pre-enabled. No manual configuration required.

Option B: Connect to an already-running browser

1. Open your browser (Chrome, Brave, Edge, etc.)
2. Navigate to chrome://inspect/#remote-debugging
3. Toggle the switch ON to enable remote debugging
4. Run chromex list to verify the connection

Important: Without step 3, chromex cannot connect to your browser. This is a one-time setup -- the setting persists across browser restarts.

Note: With Option B, Chrome will show an "Allow debugging" dialog the first time you access each tab. Click "Allow" once per tab -- the daemon keeps the session alive after that.

Quick Start

# List open tabs
chromex list
# Output: 6BE827FA  Example Domain  https://example.com

# Take a screenshot
chromex shot 6BE8 /tmp/page.png

# Get the accessibility tree with interactive refs
chromex snap 6BE8 --refs
# Output:
#   @e1 [textbox] Email
#   @e2 [textbox] Password
#   @e3 [button] Sign in

# Fill a form using refs (no CSS selectors needed!)
chromex fill 6BE8 @e1 "[email protected]"
chromex fill 6BE8 @e2 "secret123"
chromex click 6BE8 @e3

# Check Core Web Vitals
chromex perf 6BE8

Commands

<target> is a unique prefix of the targetId shown by list (e.g. 6BE827FA).

Pages & Browser