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:

1. Launch Chrome with CDP enabled: cdp_launch
2. 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:

1. First visit to a site → full scan, cache results
2. Same site later in conversation → skip scan, use cache
3. After conversation compaction → allow one fresh scan (you lost context)
4. 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