CDP MCP

A Chrome DevTools Protocol MCP server for browser automation. Built for agents that need to fill forms, navigate sites, and remember what they learn.

Why This Exists

Most browser automation MCPs are either:

Wrappers around heavyweight frameworks (Playwright, Puppeteer)
Locked to specific sites
Missing element discovery (you have to guess selectors)

CDP MCP talks directly to Chrome via the DevTools Protocol. It auto-discovers interactive elements, generates selectors for you, and verifies that interactions actually worked.

Installation

npm install
npm run build

Usage

Add to your Claude Code MCP config (~/.claude.json):

{
  "mcpServers": {
    "cdp": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/cdp-mcp/dist/index.js"]
    }
  }
}

Then either:

Launch Chrome with CDP enabled: cdp_launch
Or connect to an existing Chrome with --remote-debugging-port=9222: cdp_connect

Tools

Tool	Purpose
`cdp_launch`	Launch Chrome with CDP enabled, isolated profile
`cdp_connect`	Connect to existing Chrome instance
`cdp_list_tabs`	List all open tabs
`cdp_navigate`	Go to URL, back, forward, refresh
`cdp_find_elements`	Discover all interactive elements with auto-generated selectors
`cdp_interact`	Click, type, check, select, upload - with built-in verification
`cdp_read`	Read page text, element text, input values
`cdp_screenshot`	Capture viewport or full page
`cdp_wait`	Wait for element, text, navigation
`cdp_execute`	Run arbitrary JavaScript (escape hatch)
`cdp_list_frames`	List all frames (main + iframes)
`cdp_frame_interact`	Interact with elements inside iframes
`cdp_type_text`	Type at cursor position (for React/Vue/Angular)
`cdp_click_coordinates`	Click at x,y coordinates
`cdp_set_value`	Set input value with proper event dispatch
`cdp_monaco_editor`	Interact with Monaco/VS Code editors
`cdp_upload_shadow`	Upload files to shadow DOM file inputs
`cdp_submit_form`	Submit forms reliably (React/Vue/Angular compatible)

Site Memory Tools

Tool	Purpose
`cdp_site_scan`	Scan page structure (iframes, shadow DOM, forms) - auto-caches per epoch
`cdp_site_info`	Get stored site info for current page or domain
`cdp_site_note`	Add notes or selector patterns you learn
`cdp_site_list`	List all remembered sites
`cdp_site_clear`	Forget a site (force fresh scan)
`cdp_epoch_info`	Debug epoch tracking

Bug Tracking Tools

Tool	Purpose
`cdp_track_bug`	Track a bug in CDP-MCP (writes to BUGS.md)
`cdp_list_bugs`	List all tracked bugs
`cdp_fix_bug`	Mark a bug as fixed and remove it

Key Features

Auto-Discovery

cdp_find_elements returns every interactive element on the page with:

Tag, type, id, name, class
Associated label (from <label>, aria-label, etc.)
Auto-generated CSS selector
Visibility and position

No more guessing selectors or inspecting the DOM manually.

Built-in Verification

cdp_interact verifies that actions actually worked:

{
  "success": true,
  "action": "type",
  "selector": "#email",
  "expected": "user@example.com",
  "actual": "user@example.com",
  "verified": true
}

If a React controlled input silently rejects your value, you'll know immediately.

Site Memory

The MCP remembers what it learns about sites:

Iframe locations - Which sites use iframes and where
Shadow DOM elements - Components that need special handling
Selector patterns - CSS selectors that work for common actions
Notes - Context you add while working

Stored in ~/.claude/site-memory.json, persists across sessions.

Epoch Tracking

Site memory integrates with Claude Code's conversation compaction:

First visit to a site → full scan, cache results
Same site later in conversation → skip scan, use cache
After conversation compaction → allow one fresh scan (you lost context)
Back to caching until next compaction

This prevents redundant scanning while ensuring you re-orient after context loss.

Minimal Dependencies

ws - WebSocket client for CDP
That's it

No Playwright. No Puppeteer. Just raw CDP over WebSocket.

Example Workflow

1. cdp_connect              → Connect to Chrome on port 9222
2. cdp_navigate             → Go to a form page
3. cdp_find_elements        → Get all inputs with selectors
4. cdp_interact (type)      → Fill fields, get verification
5. cdp_interact (click)     → Submit
6. cdp_wait (navigation)    → Wait for redirect
7. cdp_read                 → Confirm success

Design Philosophy

Focused tool set - Everything an agent needs for browser automation
CSS selectors - Universal, inspectable, copy-pasteable
Verification by default - Know if it worked without extra calls
cdp_execute escape hatch - When you need raw JS, it's there

Requirements

Node.js 18+
Chrome/Chromium with --remote-debugging-port flag

License

MIT