cdp-tools-mcp

Give AI agents real debugging superpowers—breakpoints, variable inspection, and browser automation through Chrome DevTools Protocol.

npx cdp-tools-mcp@latest

Stop guessing, start debugging. AI can read your code, but it can't see what happens when it runs. This MCP server changes that—giving your agent the same debugging tools you use in DevTools: set breakpoints, inspect variables mid-execution, watch network requests, and step through code line by line.

Record once, replay forever. Found a bug that requires 5 clicks to reproduce? Record the sequence once, then replay it instantly after every fix. No tokens wasted re-navigating, no "click the blue button" back-and-forth.

Features

Your AI agent gets access to:

• 🐛 Set breakpoints and step through your code
• 🔍 Inspect variables and call stacks at runtime
• 📊 Monitor console logs and network requests
• 🌐 Automate browser interactions with smart element discovery
• 🔄 Debug both Chrome and Node.js applications simultaneously
• 🤖 Multi-agent support: Nested Claude agents can each manage their own browser tabs
• 🎯 Targeted Server Management: MCP that monitors ports and manages server processes automatically. If something fails, all tools are blocked until the LLM fixes the issue.
• 📋 Issues Tracking: Track bugs and features with recorded reproduction sequences that verify fixes automatically

Quick Start

Claude Code:

claude mcp add cdp-tools -- npx cdp-tools-mcp@latest

Claude Desktop — add to your config file:

{
  "mcpServers": {
    "cdp-tools": {
      "command": "npx",
      "args": ["-y", "cdp-tools-mcp@latest"]
    }
  }
}

Other MCP clients — run npx cdp-tools-mcp@latest via stdio transport.

Key Features

Runtime Debugging

• Breakpoint Management: Set, remove, and list breakpoints (including conditional breakpoints and logpoints)
• DOM/Event/XHR Breakpoints: Pause on DOM mutations, event dispatches, or network requests
• Execution Control: Pause, resume, step over/into/out
• Variable Inspection: Examine call stacks, variables, and scopes at runtime
• Source Map Support: Debug TypeScript code with automatic source map detection
• Universal: Works with both Chrome browsers and Node.js applications

Browser Automation (Chrome only)

• Smart Navigation: Navigate with automatic clickable element caching
• Element Discovery: Navigation automatically caches all interactive elements (links, buttons, inputs) with viewport-aware filtering
• DOM Inspection: Query elements, get properties, take screenshots
• User Interaction: Click, type, hover, press keys
• Console & Network Monitoring: Track logs and HTTP requests with deep serialization
• Storage Access: Inspect and modify localStorage, sessionStorage, cookies
• Interaction Recording: Record mouse, keyboard, and navigation events with visual overlay
• Test Export: Export recordings as Playwright or Puppeteer tests

Multi-Agent Support

• Tab Management: Nested Claude agents can each create and manage their own browser tabs within the same Chrome instance
• Connection Management: Debug Chrome and Node.js simultaneously with isolated connections
• Port Handling: Automatic port assignment prevents conflicts when running multiple sessions

Server Management

• Language-Agnostic: Run any command - npm, flask, docker, or custom scripts
• Docker Support: Native support for Docker containers and Docker Compose stacks
• Multi-Session Coordination: Multiple MCP sessions share the same dev servers without port conflicts
• Port Monitoring: Detect server failures with configurable response levels (inform, error, block)
• Persistent State: Server PIDs, ports, and config survive session restarts
• Auto-Restart: Servers with autoRun enabled restart automatically with exponential backoff
• Cross-Session Logs: File-based logging lets any session read server output

Issues Tracking

• Bug & Feature Workflow: Create issues, record reproduction steps, and verify fixes with automated replay
• Sequence-Based Verification: workOn navigates to context, resolve replays and confirms the fix

Example Usage

Web Debugging:

1. Ask Claude: "Launch Chrome and navigate to https://myapp.com"
2. Claude launches browser, caches all clickable elements
3. Ask: "Find all login-related links"
4. Claude searches cached elements instantly
5. Ask: "Click the login button and watch for errors"
6. Claude interacts and monitors console/network

Node.js Debugging:

1. Start your app: node --inspect=9229 app.js
2. Ask Claude: "Connect to my Node app and set a breakpoint in user.js line 42"
3. Trigger the code path
4. Ask: "What are the values of userId and userRole?"
5. Claude inspects variables and provides insights

Documentation

• Comprehensive Guide - Detailed usage, examples, and advanced patterns
• Tool Instructions - MCP tool reference and best practices
• Message Templates - Response formats and error messages

Why cdp-tools-mcp?

vs Chrome DevTools MCP:

• ✅ Breakpoint debugging - Set breakpoints, step through code, inspect variables at runtime
• ✅ Node.js debugging - Debug backend applications, not just browsers
• ✅ Multi-connection support - Debug Chrome and Node.js simultaneously
• ✅ Logpoints - Add logging without modifying source code
• ✅ Replay System - Record and replay command sequences for testing and automation

Best for: Backend debugging, full-stack debugging, understanding code execution flow

Chrome DevTools MCP is better for performance analysis, device emulation, and advanced browser automation.

Try It Out

Check out our test application with 8 debug challenges covering DOM bugs, network issues, breakpoints, logpoints, and multi-connection debugging.

Installation from Source

git clone https://github.com/InDate/cdp-tools-mcp.git
cd cdp-tools-mcp
npm install
npm run build
npm start

Contributing

Contributions welcome! This is a prototype for demonstrating runtime debugging capabilities for LLMs. Feel free to extend and improve it based on your needs.

License

MIT

What's New

Latest

• Issues Tracking: New issues tool for bug/feature tracking with recorded reproduction sequences and automated verification
• Recording Survives Navigation: Overlay persists across page refresh with proper connection cleanup
• Interaction Recording: Record mouse clicks, drags, scrolls, keyboard input, and navigation events with a visual overlay - add comments during recording with Ctrl+Shift+C
• Visual Replay Cursor: See exactly where clicks happen during replay with animated cursor and ripple effects
• Test Export: Export recordings as Playwright (.spec.ts) or Puppeteer (.test.js) tests with export({ name: "my-test", format: "playwright" })
• Config Management: New config tool to manage settings - switch between local/global config, backup, reset, and view current configuration
• Cross-Directory Server Access: Use global: true flag to access servers started from a different working directory
• DOM/Event/XHR Breakpoints: Pause on DOM mutations (setDOMBreakpoint), event dispatches (setEventBreakpoint), or network requests (setXHRBreakpoint) using CDP's DOMDebugger domain
• Replay Repeat Action: Instantly re-execute commands from history with replay({ action: 'repeat', indices: [0, 1, 2] }) - each tool response now shows its history index for easy repetition
• UI Verification: Detect dead buttons, broken links, small touch targets, and overflow issues with CDP-based verification - no heuristics, just facts
• DOM Change Detection: See exactly what changed after each click, type, or hover - no more guessing what a button did
• Port Monitoring: Detect server failures with monitorPort action - configurable levels (inform, error, block) affect tool responses when monitored ports go down
• Docker Support: Server management now supports Docker containers and Docker Compose stacks alongside native processes
• Language-Agnostic Servers: Generic command execution replaces npm-specific logic - run any command (flask, python, go, etc.)
• Variable Inspection Fallbacks: getVariables gracefully degrades when data exceeds token limits (full → depth reduced → names only → counts only)
• Stale Connection Cleanup: Auto-detects and removes dead connections when Chrome is killed externally or tabs are closed
• Breakpoint Pause Detection: Input actions now detect and report when they trigger breakpoints
• Multi-Session Server Coordination: Multiple MCP sessions share dev servers with persistent state, auto-restart, and cross-session log access
• Webpack Eval Support: Code search now extracts actual source from webpack eval wrappers
• Lazy Source Map Loading: On-demand loading improves startup performance
• Cache-Busting Breakpoints: Breakpoints survive rebuilds with changing query params
• Flexible Connection References: Lookups now tolerate minor formatting variations
• Enhanced Replay System: Record and replay command sequences for testing and automation
• Conditional Commands: Sequences can branch based on runtime conditions (selectors, URLs, cookies, localStorage) with configurable depth limits
• Smart Element Caching: Navigation automatically caches all clickable elements for instant discovery
• Viewport-Aware Filtering: Shows only visible elements by default, searches all when filtering
• Consolidated Tool API: Action-based tool schemas reduce tool count and improve usability
• Debug Logging: Track server operations with setDebugLogging({ enabled: true })

See the docs for detailed feature documentation.