ChromeDebug MCP

ChromeDebug MCP is a Model Context Protocol (MCP) server that gives AI assistants like Claude Code full control over a Chrome browser instance. It provides comprehensive browser automation, debugging, and screen recording capabilities optimized for AI-assisted development.

🎥 See It In Action

Watch the demo video to see how ChromeDebug MCP works:

▶️ Watch Demo Video

Quick Start

Installation from npm

Install globally

npm install -g @dynamicu/chromedebug-mcp

Or install locally in your project

npm install @dynamicu/chromedebug-mcp

Want unlimited recordings and advanced features? See Installing PRO Version below for automated PRO installation.

Chrome Extension Installation

Install the Chrome extension to enable visual element selection and recording features:

🌐 Install from Chrome Web Store

• ✅ 5 recordings per day (FREE version)
• ✅ Visual element selection
• ✅ Full MCP integration
• ✅ Automatic updates

Development Installation

Clone and install from source

git clone https://github.com/dynamicupgrade/ChromeDebug.git cd ChromeDebug npm install

Installing PRO Version

ChromeDebug PRO adds advanced features including:

• Function call tracking - Record and replay function execution traces
• Advanced debugging - Enhanced breakpoint and inspection capabilities
• Unlimited recordings - No daily recording limits
• Priority support and updates

🎥 PRO Installation Video

Watch the step-by-step installation guide:

▶️ Watch PRO Installation Guide

Installation Steps

After purchasing ChromeDebug PRO from LemonSqueezy:

1. Download your PRO extension from the purchase confirmation email (you'll receive a ZIP file named chromedebug-extension-pro.zip)
2. Run the installer:
   chromedebug-mcp install-pro \
   --license YOUR_LICENSE_KEY \
   --extension-path ~/Downloads/chromedebug-extension-pro.zip
3. Restart your terminal to load the new environment variable
4. Launch Chrome - PRO features are now active!

What the Installer Does

The install-pro command:

• ✓ Validates your license key format
• ✓ Extracts the PRO extension to ~/.chromedebug-pro/extension
• ✓ Saves your license information securely to ~/.chromedebug-pro/license.json
• ✓ Configures your shell environment automatically (exports CHROMEDEBUG_EXTENSION_PATH)
• ✓ Creates an installation log at ~/.chromedebug-pro/install.log for troubleshooting

The environment variable CHROMEDEBUG_EXTENSION_PATH is automatically detected by Chrome Controller when launching Chrome, allowing it to load the PRO extension instead of the bundled FREE version.

Verifying PRO Installation

Check that PRO is correctly installed:

Verify environment variable is set

echo $CHROMEDEBUG_EXTENSION_PATH

Should output: /Users/YOUR_USERNAME/.chromedebug-pro/extension

Check license file

cat ~/.chromedebug-pro/license.json

When you launch Chrome with chromedebug-mcp, you should see:

• "ChromeDebug MCP Assistant PRO" in chrome://extensions/ (with function tracking features enabled)

Troubleshooting PRO Installation

Environment variable not set after installation:

• Restart your terminal or run: source ~/.zshrc (or ~/.bashrc for Bash users)
• If still not set, manually add to your shell config:
  export CHROMEDEBUG_EXTENSION_PATH="$HOME/.chromedebug-pro/extension"

Chrome still loading FREE version:

• Verify the environment variable is set: echo $CHROMEDEBUG_EXTENSION_PATH
• Close ALL Chrome windows and restart ChromeDebug MCP
• Check installation log: cat ~/.chromedebug-pro/install.log

License validation errors:

• Verify you copied the full license key from your purchase email
• License format should be: LICENSEID-HASH (e.g., ABC12345-0123456789ABCDEF)
• Check for extra spaces or line breaks when copying

Extension ZIP file not found:

• Verify the path to your downloaded ZIP file is correct
• Use ~ for home directory: ~/Downloads/chromedebug-extension-pro.zip
• Check file permissions: ls -la ~/Downloads/chromedebug-extension-pro.zip

Need help?

• Check installation log: ~/.chromedebug-pro/install.log
• Open an issue: GitHub Issues

Usage

As MCP Server

Quick Setup (Claude Code CLI)

macOS / Linux:

claude mcp add chromedebug -s user -- chromedebug-mcp

Windows (WSL2):

claude mcp add chromedebug -s user -- wsl chromedebug-mcp

The MCP server will automatically start both the stdio MCP server and HTTP server for Chrome extension integration.

Manual Configuration (Any MCP Client)

If you're not using Claude Code CLI or want to configure manually, add this to your MCP settings file:

Location: ~/.claude/config.json or your MCP client's configuration file

{ "mcpServers": { "chromedebug": { "command": "chromedebug-mcp" } } }

For WSL2 users:

{ "mcpServers": { "chromedebug": { "command": "wsl", "args": ["chromedebug-mcp"] } } }

Windows Setup Details

⚠️ Important: WSL2 Recommended for Windows Users

ChromeDebug MCP uses stdio-based communication which works best on Unix systems. For Windows users, we strongly recommend using WSL2 for full compatibility.

WSL2 Setup (5 minutes):

1. Install WSL2 (PowerShell as Administrator):
   wsl --install
2. Restart your computer
3. Open WSL terminal and install Node.js:
   sudo apt update
   sudo apt install nodejs npm -y
4. Install ChromeDebug in WSL:
   npm install -g @dynamicu/chromedebug-mcp
5. Configure Claude Code to use WSL:
   claude mcp add chromedebug -s user -- wsl chromedebug-mcp
6. Verify it works:
   claude mcp list

Should show: chromedebug: wsl chromedebug-mcp - ✓ Connected

Alternative: Native Windows (Limited Support)

If you cannot use WSL2, you can force native Windows mode, but stdio communication may be unreliable:

Set environment variable to enable native Windows mode

set CHROMEDEBUG_FORCE_WINDOWS=1 chromedebug-mcp --help

Note: Native Windows may experience stdio communication issues due to cmd.exe limitations. WSL2 is strongly recommended for the best experience.

Standalone HTTP Server (New in v2.4.3)

For Windows users or those who prefer to run services separately, you can start the HTTP server independently:

Start HTTP server only (no MCP)

chromedebug-mcp-server

With options

chromedebug-mcp-server --verbose --port 3000

Available Options:

• --port PORT - Specify HTTP server port (optional, auto-discovers if not set)
• --verbose - Enable verbose logging
• --debug - Enable debug mode
• --no-cleanup - Skip process cleanup on startup
• --session-id ID - Set custom session ID

Use Cases:

• Windows users who want Chrome extension support without running full MCP server
• Development environments where you want HTTP server running persistently
• Situations where MCP and HTTP servers should run in separate processes

Embedded HTTP Server

Chrome Debug can automatically start an embedded HTTP server for Chrome extension communication. The server uses ports configured in config/chrome-pilot-config.json (default: 3001, 3000, 3002, 3028). The server provides these REST API endpoints:

Endpoint	Method	Description	Body
/chromedebug/evaluate	POST	Evaluate expression	{ "expression": "window.user" }
/chromedebug/scopes	GET	Get scope variables	-
/chromedebug/logs	GET	Get recent console logs	-
/chromedebug/screenshot	GET	Take screenshot	{ "type": "jpeg", "fullPage": true, "path": "/path/to/save.jpg" }
/chromedebug/dom-intent	POST	Process natural language DOM commands	{ "selector": "#element", "instruction": "make it blue" }
/chromedebug/status	GET	Check server and Chrome connection status	-
/chromedebug/upload/:dataType	POST	Upload screen recording with logs	FormData with video file, logs JSON, and duration
/chromedebug/recording/:id	GET	Retrieve a recording by ID	-
/chromedebug/workflow-recording	POST	Save workflow recording	{ "sessionId": "...", "actions": [...], "logs": [...] }
/chromedebug/workflow-recording/:sessionId	GET	Get workflow recording	-
/chromedebug/restore-point	POST	Save restore point	{ "workflowId": "...", "domSnapshot": {...}, ... }
/chromedebug/restore-point/:id	GET/DELETE	Get or delete restore point	-
/chromedebug/restore-points/:workflowId	GET	List restore points for workflow	-

MCP Tools

When used as an MCP server, Chrome Debug exposes these tools:

• launch_chrome - Launch a Chrome browser instance
• evaluate_expression - Evaluate JavaScript expression
• get_scopes - Get scope variables
• get_logs - Get console logs
• take_screenshot - Take a screenshot
• get_page_content - Get page content (text, HTML, and DOM structure)
• check_connection - Check Chrome connection status
• force_reset - Force reset Chrome instance
• get_selected_element - Get info about element selected via extension
• apply_css_to_selected - Apply CSS to the selected element
• execute_js_on_selected - Execute JavaScript on the selected element
• clear_selected_element - Clear the current selection
• get_workflow_recording - Get a workflow recording with actions and logs
• list_workflow_recordings - List all workflow recordings
• save_restore_point - Save a restore point for the current browser state
• restore_from_point - Restore browser to a saved restore point
• list_restore_points - List restore points for a workflow

Example

Start the server (automatically kills existing processes and finds available port)

npm start

The server will display the port it's running on:

🚀 Starting Chrome Debug Server on port 3000...

📍 Extension should connect to: http://localhost:3000

🔧 MCP tools will use this port for API calls

In another terminal, test the API (use the port shown in startup)

curl -X POST http://localhost:3000/chromedebug/pause curl -X POST http://localhost:3000/chromedebug/evaluate
-H "Content-Type: application/json"
-d '{"expression": "document.title"}'

Chrome Extension - Visual Element Selection

Chrome Debug includes a Chrome extension that enables visual element selection for MCP control:

Installing the Extension

Option 1: Chrome Web Store (Recommended - FREE Version)

Install the FREE version directly from the Chrome Web Store:

• ✅ 5 recordings per day
• ✅ Full MCP integration
• ✅ Visual element selection
• ✅ Automatic updates
• ✅ No manual installation needed

Option 2: Manual Installation (Development)

1. Open Chrome and navigate to chrome://extensions/
2. Enable "Developer mode"
3. Click "Load unpacked" and select the chrome-extension directory

Option 3: PRO Version (Unlimited) - Automated Installation

For unlimited recordings and advanced features, purchase the PRO version:

💎 Get PRO Version

• ✅ Unlimited recordings
• ✅ Advanced function tracing
• ✅ Enhanced capture features
• ✅ Priority support

Installation: PRO extension is automatically installed via the chromedebug-mcp install-pro command. See the Installing PRO Version section above for detailed instructions.

Using the Extension

1. Element Selection
   • Click on any element on a webpage
   • The element is sent to Chrome Debug and highlighted in pink
   • Use Claude MCP tools to modify the selected element:
     * get_selected_element - View the currently selected element
     * apply_css_to_selected - Apply CSS styles to the element
     * execute_js_on_selected - Execute JavaScript on the element
     * clear_selected_element - Clear the selection
2. Workflow Recording
   • Click "Start Workflow Recording" to record user interactions
   • All clicks, inputs, and drags are captured
   • Console logs can be included in the recording
   • Workflows can be replayed later for debugging

Managing License Activations

Chrome Debug uses a license activation system to prevent activation limit exhaustion when reinstalling the extension.

The Problem

When you uninstall and reinstall the Chrome extension, it clears local storage and generates a new activation instance. With a typical 3-activation limit, frequent reinstalls can exhaust your available slots.

The Solution: Activation Manager

Chrome Debug now includes an Activation Manager that automatically handles this scenario:

How It Works:

1. When activation limit is reached, the Activation Manager opens automatically
2. Shows all your current activations with device info (e.g., "macOS 14.0 • Chrome 121")
3. Identifies your current device (highlighted in green)
4. You select which activation to deactivate
5. Extension automatically retries activation on current device

Example: Reinstalling on Same Machine

You reinstall the extension on your laptop:
→ Try to activate license
→ Activation Manager shows:
  • Activation 1: "macOS 14.0 • Chrome 120" (Oct 10) ← OLD instance
  • Activation 2: "Windows 11 • Chrome 121" (Oct 12)
  • Activation 3: "Linux • Firefox 119" (Oct 14)
→ You recognize #1 is this same laptop
→ Click "Deactivate" on #1
→ Extension automatically activates new instance
→ Result: Still 3/3 slots, seamless experience

Best Practices:

• Before uninstalling: No action needed - Activation Manager handles it
• Multiple devices: Activation Manager helps track which is which
• Unused devices: Periodically deactivate machines you no longer use

FAQ

**Q: What happens if I forget which activation is which?**A: The Activation Manager shows device information (OS, browser version) and activation dates. Your current device is highlighted in green.

**Q: Can I deactivate my current device?**A: No, the button is disabled for your current device to prevent accidental lockout.

**Q: Does reinstalling the browser consume an activation?**A: Yes, because local storage is cleared. Use the Activation Manager to deactivate the old instance first or after reinstalling.

Development

npm run dev # Run with --watch flag

Example Prompts for Claude

Once Chrome Debug is installed as an MCP server, you can use these prompts with Claude:

Basic Browser Control

• "Launch Chrome and navigate to https://example.com"
• "Evaluate document.title in the browser"
• "Get all the links on the current page"
• "Take a screenshot of the current page"

Web Scraping & Automation

• "Navigate to https://news.ycombinator.com and get the titles of the top 5 stories"
• "Fill out the search form with 'JavaScript' and submit it"
• "Click the login button and enter username 'test' and password 'demo'"
• "Monitor the network requests and show me all API calls"

Debugging Web Apps

• "Show me all console errors on this page"
• "Watch for any uncaught exceptions and report them"
• "Profile the page load performance"
• "Check if there are any memory leaks by monitoring heap usage"

Advanced Debugging

• "Set conditional breakpoints when userId === 5"
• "Trace the execution flow of the checkout() function"
• "Show me all event listeners attached to the submit button"
• "Evaluate the current state of the Redux store"

Visual Element Modification

After selecting an element with the Chrome extension:

• "Show me what element is currently selected"
• "Make the selected element blue with rounded corners"
• "Apply CSS: background-color: #2196F3 !important; padding: 20px !important"
• "Hide the selected element"
• "Execute JavaScript to get the element's text content"
• "Click the selected element"
• "Clear the selected element"

Screen Recording Feature

Chrome Debug includes a powerful screen recording feature that captures video of the current tab along with synchronized console logs. This helps users explain issues more effectively by providing visual context with technical details.

How to Use Recording

1. Start Recording:
   • Click the Chrome Debug extension icon
   • Click "Start Recording" button
   • The browser will prompt for permission to capture the tab
   • Recording starts immediately after permission is granted
2. During Recording:
   • The button changes to "Stop Recording" and pulses red
   • A timer shows the recording duration
   • All console logs (log, warn, error, info) are captured with timestamps
   • Continue using the browser normally - all interactions are recorded
3. Stop Recording:
   • Click "Stop Recording" button
   • The video and logs are automatically uploaded to the Chrome Debug server
   • You'll receive a recording ID (e.g., rec_1234567890_abc123)
4. Share with Claude:
   • Tell Claude: "Get recording rec_1234567890_abc123"
   • Claude will retrieve the video and synchronized console logs
   • The logs show precise timing relative to the video

Recording Details

• Video Format: WebM with VP9 codec for efficient compression
• Resolution: Up to 1920x1080 (adapts to tab size)
• Console Logs: Captured with millisecond precision timestamps
• User Interactions: Mouse clicks, keyboard input, scrolling automatically captured
• Storage: Recordings are stored temporarily (last 10 recordings kept)
• No Audio: Audio is not captured to focus on visual debugging

Captured Interactions

Screen recordings now automatically capture all user interactions:

• Clicks: Position, element selector, XPath, and clicked text
• Input: Text entered into forms with field selectors
• Keypresses: Special keys like Enter, Escape, Tab
• Scrolling: Scroll positions throughout the recording

Example Use Cases

• Bug Reports: Record the exact steps to reproduce an issue
• UI Problems: Show visual glitches or unexpected behavior
• Performance Issues: Capture slow interactions with console timing
• Complex Workflows: Document multi-step processes that are hard to explain
• User Testing: Review exactly how users interact with your interface

MCP Tools for Recording

• get_recording - Retrieve a recording by ID to analyze video and logs
• chrome_pilot_show_frames - Display frame-by-frame recording with interactions and logs
• get_frame - Get specific frame with its interactions and console logs
• get_screen_interactions - Query specific interaction data from recordings