Chrome DevTools MCP Helper

A powerful browser automation CLI built on Chrome DevTools Protocol with AI-optimized features and full parity with industry-leading browser automation tools.

Features

• Complete Browser Control: Navigate, interact, and automate Chrome/Chromium browsers
• AI-Optimized Snapshots: Accessibility tree with deterministic element references (@e1, @e2, etc.)
• Multiple Selector Types: CSS selectors, XPath, refs, and semantic locators
• Device Emulation: Mobile/desktop device presets, custom viewports, geolocation
• State Management: Save and restore browser state (cookies, localStorage, sessionStorage)
• Comprehensive Command Set: 40+ commands for navigation, interaction, debugging
• Session Isolation: Multiple browser instances with separate user data directories

Installation

# Install dependencies
bun install

# Build the project
bun run build

# Run the CLI
bun run src/cli.ts <command> [options]

Quick Start

# Navigate to a URL
bun run src/cli.ts open https://example.com

# Take an AI-optimized snapshot with interactive elements only
bun run src/cli.ts snapshot -i --json

# Click an element using ref
bun run src/cli.ts click @e1

# Fill a form field
bun run src/cli.ts fill @e2 "[email protected]"

# Emulate iPhone 14
bun run src/cli.ts set-device "iPhone 14"

# Save browser state
bun run src/cli.ts state-save auth.json

# Take a screenshot
bun run src/cli.ts screenshot page.png

Command Reference

Navigation Commands

Navigate to URL

# Aliases: open, goto, navigate
bun run src/cli.ts open <url>
bun run src/cli.ts goto https://example.com --wait-until load

Navigation Controls

# Go back in history
bun run src/cli.ts back

# Go forward in history
bun run src/cli.ts forward

# Reload page (aliases: reload, refresh)
bun run src/cli.ts reload
bun run src/cli.ts reload --hard  # Force reload

Tab Management

# Create new tab (aliases: tab-new, new-page)
bun run src/cli.ts tab-new https://example.com

# List all tabs
bun run src/cli.ts tab-list

# Switch to tab by index
bun run src/cli.ts tab-switch 2

# Close tab
bun run src/cli.ts tab-close

Element Interaction

Snapshot - AI-Optimized Element Discovery

# Get accessibility tree with refs
bun run src/cli.ts snapshot

# Interactive elements only
bun run src/cli.ts snapshot -i

# JSON output for AI agents
bun run src/cli.ts snapshot --json

# Compact view
bun run src/cli.ts snapshot -c

Click Operations

# Single click (supports refs and CSS selectors)
bun run src/cli.ts click @e1
bun run src/cli.ts click "button.submit"

# Double click (aliases: dblclick, double-click)
bun run src/cli.ts dblclick @e2

Text Input

# Fill input field (aliases: fill, type)
bun run src/cli.ts fill @e3 "[email protected]"
bun run src/cli.ts type "#email" "[email protected]"

# Press keyboard keys
bun run src/cli.ts press Enter
bun run src/cli.ts press "Ctrl+A"

Element Focus and Hover

# Focus element
bun run src/cli.ts focus @e4

# Hover over element
bun run src/cli.ts hover "nav .menu-item"

Device Emulation

Device Presets

# Emulate device (aliases: emulate, set-device)
bun run src/cli.ts set-device "iPhone 14"
bun run src/cli.ts set-device "iPad Pro"
bun run src/cli.ts set-device "Pixel 5"

Custom Viewport

# Set viewport size (aliases: resize, set-viewport)
bun run src/cli.ts set-viewport 1920 1080

Geolocation

# Set geographic location
bun run src/cli.ts set-geo 37.7749 -122.4194  # San Francisco

Media Queries

# Set color scheme (dark/light)
bun run src/cli.ts set-media dark
bun run src/cli.ts set-media light

Element Property Inspection

Get Element Properties (New command)

# Get element text
bun run src/cli.ts get --property text --selector @e1

# Get attribute value
bun run src/cli.ts get --property attr --selector @e2 --attr href

# Get computed property
bun run src/cli.ts get --property property --selector input.email --prop value

# JSON output for AI processing
bun run src/cli.ts get --property text --selector @e1 --json

Typical Workflow:

# 1. Take snapshot to find element refs
bun run src/cli.ts snapshot -i --json

# 2. Get text content from element
bun run src/cli.ts get --property text --selector @e1

# 3. Get attributes (links, form values, etc.)
bun run src/cli.ts get --property attr --selector @e3 --attr href --json

State Management

Save/Load Browser State

# Save authentication state
bun run src/cli.ts state-save auth.json

# Restore saved state
bun run src/cli.ts state-load auth.json

The state file includes:

• Cookies
• localStorage
• sessionStorage
• Current URL

Debugging & Output

Screenshots

# Take screenshot
bun run src/cli.ts screenshot page.png

# Full page screenshot
bun run src/cli.ts screenshot --full-page output.png

Script Evaluation

# Execute JavaScript in page context
bun run src/cli.ts eval "document.title"
bun run src/cli.ts eval "window.scrollTo(0, document.body.scrollHeight)"

Console Messages

# List console messages
bun run src/cli.ts console

# Get specific console message
bun run src/cli.ts console 0

Chrome M144+ Remote Debugging

Chrome M144+ removed the HTTP discovery API (/json/version). Use the internal session debugging mode instead:

1. Open chrome://inspect/#remote-debugging in Chrome
2. Click "Discover network targets" and enable it
3. Run:

bun run src/cli.ts connect --auto

Other Chromium browsers / pre-M144

# Connect by port (Chrome must be running with --remote-debugging-port=9222)
bun run src/cli.ts connect 9222

# Connect to a remote host
bun run src/cli.ts connect --auto 192.168.1.10:9222

Session Management

User Data Directory

# Use custom user data directory for session isolation
bun run src/cli.ts open https://example.com --user-data-dir=/tmp/session1
bun run src/cli.ts open https://example.com --user-data-dir=/tmp/session2

Close Browser

# Close the browser instance
bun run src/cli.ts close

AI-Optimized Features

Ref System

The snapshot command generates AI-friendly element references (@e1, @e2, etc.) that are deterministic and easy to use:

# 1. Take snapshot to discover elements
bun run src/cli.ts snapshot -i --json
# Output: {"elements": [{"ref": "@e1", "description": "button 'Submit'"}], "success": true}

# 2. Use refs in subsequent commands
bun run src/cli.ts click @e1
bun run src/cli.ts fill @e2 "[email protected]"

JSON Output Mode

Many commands support --json flag for structured output perfect for AI agents:

bun run src/cli.ts snapshot --json
bun run src/cli.ts console --json

Advanced Options

Timeouts

# Set command timeout (in milliseconds)
bun run src/cli.ts open https://example.com --timeout=10000

MCP Connection Type

# Use stdio (default)
bun run src/cli.ts open https://example.com --mcp-type=stdio

# Use HTTP
bun run src/cli.ts open https://example.com --mcp-type=http

Debug Mode

# Enable debug output
DEBUG=1 bun run src/cli.ts open https://example.com

Command Aliases Quick Reference

| Command | Aliases | |---------|---------| | navigate | open, goto | | tab-new | new-page | | tab-close | close-page | | tab-list | list-pages | | reload | refresh | | dblclick | double-click | | fill | type | | snapshot | take-snapshot | | emulate | set-device | | resize | set-viewport |

Architecture

This CLI is built on:

• Chrome DevTools Protocol (CDP): Low-level browser automation protocol
• MCP (Model Context Protocol): Integration layer for AI agents
• Bun Runtime: Fast TypeScript/JavaScript runtime
• modality-ai: AI-friendly browser automation toolkit

Testing

# Run test suite
bun test

# Run with coverage
bun test --coverage

# Type checking
bun run build:types

Use Cases

Automated Testing

bun run src/cli.ts open https://app.example.com
bun run src/cli.ts fill "#username" "testuser"
bun run src/cli.ts fill "#password" "testpass"
bun run src/cli.ts click "button[type=submit]"
bun run src/cli.ts screenshot logged-in.png

Web Scraping

bun run src/cli.ts open https://news.example.com
bun run src/cli.ts snapshot -i --json > elements.json
bun run src/cli.ts eval "document.querySelector('h1').textContent"

Mobile Testing

bun run src/cli.ts set-device "iPhone 14"
bun run src/cli.ts open https://mobile.example.com
bun run src/cli.ts screenshot mobile-view.png

AI Agent Automation

# AI-friendly workflow with refs
bun run src/cli.ts open https://example.com
bun run src/cli.ts snapshot -i --json | jq '.elements[] | select(.description | contains("Login"))'
bun run src/cli.ts click @e1

Known Issues

get Command Status

The get command has been implemented to support retrieving element properties, text content, and attributes (matching agent-browser API). However, the current version of the chrome-devtools-mcp server has a parameter validation issue with the evaluate_script tool that prevents full functionality.

Status: Ready for when chrome-devtools-mcp is updated to fix the parameter schema.

Contributing

Contributions are welcome! Please ensure:

• All tests pass (bun test)
• Type checking succeeds (bun run build:types)
• Code follows existing patterns and style

License

ISC

Related Projects

• chrome-devtools-mcp - The underlying MCP server
• agent-browser - Industry-leading browser automation CLI
• Playwright - Browser automation framework
• Puppeteer - Node.js library for Chrome/Chromium automation