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_executeescape hatch - When you need raw JS, it's there
Requirements
- Node.js 18+
- Chrome/Chromium with
--remote-debugging-portflag
License
MIT