chrome-devtools-mcp

Chrome DevTools MCP

A Model Context Protocol (MCP) server that provides Chrome DevTools Protocol integration through MCP. This allows you to debug web applications by connecting to Chrome's developer tools.

Available as a Claude Desktop Extension (.dxt) for easy one-click installation!

What This Does

This MCP server acts as a bridge between Claude and Chrome's debugging capabilities. Once installed in Claude Desktop, you can:

• Connect Claude to any web application running in Chrome
• Debug network requests, console errors, and performance issues
• Inspect JavaScript objects and execute code in the browser context
• Monitor your application in real-time through natural conversation with Claude

Note: This is an MCP server that runs within Claude Desktop - you don't need to run any separate servers or processes.

Features

• Network Monitoring: Capture and analyse HTTP requests/responses with filtering options
• Console Integration: Read browser console logs, analyse errors, and execute JavaScript
• Performance Metrics: Timing data, resource loading, and memory utilisation
• Page Inspection: DOM information, page metrics, and multi-frame support
• Storage Access: Read cookies, localStorage, and sessionStorage
• Real-time Monitoring: Live console output tracking
• Object Inspection: Inspect JavaScript objects and variables

Installation

Option 1: Claude Desktop Extension (Easiest)

Download the pre-built extension:

1. Download the latest .dxt file from Releases
2. Open Claude Desktop
3. Go to Extensions and install the downloaded .dxt file
4. Configure Chrome path if needed in extension settings

The extension includes all dependencies and is ready to use immediately!

Option 2: MCP CLI (Advanced)

Quick Install (most common):

Note: The mcp command is part of the Python MCP SDK. Install it with pip install mcp if not already available.

All Installation Options:

Option 3: Claude Code Integration

For Claude Code CLI users:

1. Clone this repository

2. Install dependencies with UV (creates venv)

3. Add MCP server using Claude CLI with absolute paths

IMPORTANT: Claude Code needs absolute paths to both the Python interpreter and the server script to work correctly.

Recommended setup using absolute paths:

Alternative: Using the system Python (if dependencies are installed globally):

With custom scope:

4. Verify installation

Common Path Issues and Solutions:

• Problem: "python: command not found" or "server.py not found"
  • Solution: Use absolute paths as shown above
• Problem: "ModuleNotFoundError" when server starts
  • Solution: Use the venv Python interpreter that has dependencies installed
• Problem: Server doesn't start or shows as disconnected
  • Solution: Test the command manually: /path/to/.venv/bin/python /path/to/server.py

Option 4: Manual Claude Desktop Setup

1. Clone this repository

2. Install dependencies

With uv (recommended):

With pip:

3. Add to Claude Desktop configuration

Edit your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

4. Restart Claude Desktop

Verify Installation

After installation (either method), verify the server is available:

1. Open Claude Desktop
2. Look for MCP tools in the conversation
3. Try a simple command: get_connection_status()

Alternative MCP Clients

For other MCP clients, run the server directly:

Quick Start

Once installed in Claude Desktop, you can start debugging any web application:

Debug Your Web Application

One-step setup (recommended):

Replace localhost:3000 with your application's URL

If Chrome isn't found automatically:

Use the chrome_path parameter to specify a custom Chrome location

This command will:

• Start Chrome with debugging enabled
• Navigate to your application
• Connect the MCP server to Chrome

Manual setup (if you prefer step-by-step):

Start Debugging

Once connected, use these commands:

• get_network_requests() - View HTTP traffic
• get_console_error_summary() - Analyse JavaScript errors
• inspect_console_object("window") - Inspect any JavaScript object

Available MCP Tools

Chrome Management

• start_chrome(port?, url?, headless?, chrome_path?, auto_connect?) - Start Chrome with remote debugging and optional auto-connection
• start_chrome_and_connect(url, port?, headless?, chrome_path?) - Start Chrome, connect, and navigate in one step
• connect_to_browser(port?) - Connect to existing Chrome instance
• navigate_to_url(url) - Navigate to a specific URL
• disconnect_from_browser() - Disconnect from browser
• get_connection_status() - Check connection status

Network Monitoring

• get_network_requests(filter_domain?, filter_status?, limit?) - Get network requests with filtering
• get_network_response(request_id) - Get detailed response data including body

Console Tools

• get_console_logs(level?, limit?) - Get browser console logs
• get_console_error_summary() - Get organized summary of errors and warnings
• execute_javascript(code) - Execute JavaScript in browser context
• clear_console() - Clear the browser console
• inspect_console_object(expression) - Deep inspect any JavaScript object
• monitor_console_live(duration_seconds) - Monitor console output in real-time

Page Analysis

• get_page_info() - Get comprehensive page metrics and performance data
• evaluate_in_all_frames(code) - Execute JavaScript in all frames/iframes
• get_performance_metrics() - Get detailed performance metrics and resource timing

Storage & Data

• get_storage_usage_and_quota(origin) - Get storage usage and quota information
• clear_storage_for_origin(origin, storage_types?) - Clear storage by type and origin
• get_all_cookies() - Get all browser cookies
• clear_all_cookies() - Clear all browser cookies
• set_cookie(name, value, domain, path?, expires?, http_only?, secure?, same_site?) - Set a cookie
• get_cookies(domain?) - Get browser cookies with optional domain filtering
• get_storage_key_for_frame(frame_id) - Get storage key for a specific frame
• track_cache_storage(origin, enable?) - Enable/disable cache storage tracking
• track_indexeddb(origin, enable?) - Enable/disable IndexedDB tracking
• override_storage_quota(origin, quota_size_mb?) - Override storage quota

Use Cases

Debugging API Calls in Your Web Application

When your web application makes API calls that fail or return unexpected data:

Easy setup: Use the one-step command to start Chrome and navigate to your app:

Example workflow:

Manual setup (if you prefer):

1. Start Chrome: Use start_chrome()
2. Navigate to your app: Use navigate_to_url("localhost:3000")
3. Connect: Use connect_to_browser()
4. Monitor network traffic: Use get_network_requests() to see all API calls

Checking JavaScript Console Errors

When your web application has JavaScript errors or unexpected behaviour:

1. Navigate to your application in the connected Chrome instance
2. Check for console errors: Use get_console_error_summary() to see all errors
3. Monitor live errors: Use monitor_console_live(10) to watch for new errors as you interact
4. Inspect variables: Use inspect_console_object("myVariable") to examine application state

Example workflow:

Performance Debugging

When your web application loads slowly or uses too much memory:

1. Load your application in the connected browser
2. Check page metrics: Use get_page_info() to see load times and resource counts
3. Analyse performance: Use get_performance_metrics() to see detailed timing data
4. Monitor memory usage: Check the memory information in the performance metrics

Example workflow:

Debugging Authentication Issues

When login or session management isn't working:

1. Navigate to your login page
2. Check cookies: Use get_cookies() to see authentication cookies
3. Monitor network during login: Use monitor_console_live() and get_network_requests() during the login process
4. Examine stored data: Use JavaScript execution to check localStorage/sessionStorage

Example workflow:

DOM Element Inspection

• get_document(depth?, pierce?) - Retrieve DOM document structure
• query_selector(node_id, selector) - Find single element by CSS selector
• query_selector_all(node_id, selector) - Find multiple elements by CSS selector
• get_element_attributes(node_id) - Get all attributes of an element
• get_element_outer_html(node_id) - Get outer HTML of an element
• get_element_box_model(node_id) - Get layout information
• describe_element(node_id, depth?) - Get detailed element description
• get_element_at_position(x, y) - Get element at screen position
• search_elements(query) - Search DOM elements by text/attributes
• focus_element(node_id) - Focus a DOM element

CSS Style Analysis

• get_computed_styles(node_id) - Get computed CSS styles
• get_inline_styles(node_id) - Get inline styles
• get_matched_styles(node_id) - Get all CSS rules matching an element
• get_stylesheet_text(stylesheet_id) - Get stylesheet content
• get_background_colors(node_id) - Get background colors and fonts
• get_platform_fonts(node_id) - Get platform font information
• get_media_queries() - Get all media queries
• collect_css_class_names(stylesheet_id) - Collect CSS class names
• start_css_coverage_tracking() - Start CSS coverage tracking
• stop_css_coverage_tracking() - Stop and get CSS coverage results

Common Commands

Configuration

Environment Variables

• CHROME_DEBUG_PORT - Chrome remote debugging port (default: 9222)

MCP Compatibility

• MCP Protocol Version: 2024-11-05
• Minimum Python Version: 3.10+
• Supported MCP Clients: Claude Desktop, any MCP-compatible client
• Package Manager: uv (recommended) or pip

Usage Workflow

Prerequisites (Your Development Environment)

• Have your web application running (e.g., npm run dev, python -m http.server, etc.)
• Note the URL where your application is accessible

Debugging Session

1. Connect to your application via Claude Desktop:
   start_chrome_and_connect("localhost:3000")
   Replace with your application's URL
2. Debug your application using the MCP tools:
   • Monitor network requests
   • Check console errors
   • Inspect JavaScript objects
   • Analyse performance
3. Make changes to your code in your editor
4. Refresh or interact with your application
5. Continue debugging with real-time data

Manual Connection (Alternative)

If you prefer step-by-step control:

1. start_chrome() - Launch Chrome with debugging
2. navigate_to_url("your-app-url") - Navigate to your application
3. connect_to_browser() - Connect the MCP server
4. Use debugging tools as needed

Security Notes

• Only use with development environments
• Never connect to production Chrome instances
• The server is designed for localhost debugging only
• No data is stored permanently - all data is session-based

Troubleshooting

Server Shows as "Disabled" in Claude Desktop

If the server appears in Claude but shows as "disabled", try these steps:

1. Check Claude Desktop logs:
   • macOS: ~/Library/Logs/Claude/mcp*.log
   • Windows: %APPDATA%/Claude/logs/mcp*.log
2. Common fixes:
   # Reinstall with verbose output mcp remove "Chrome DevTools MCP" mcp install server.py -n "Chrome DevTools MCP" --with-editable . -v CHROME_DEBUG_PORT=9222 # Check installation status mcp list # Test the server manually python3 server.py
3. Check dependencies:
   # Ensure all dependencies are available pip install mcp websockets aiohttp # Test imports python3 -c "from server import mcp; print('OK')"
4. Restart Claude Desktop completely (quit and reopen)

Installation Issues

• MCP CLI not found: Install MCP CLI from the Python MCP SDK with pip install mcp
• Server not appearing in Claude:
  • For MCP CLI: Run mcp list to verify the server is installed
  • For manual setup: Check Claude Desktop configuration file path and JSON syntax
• Import errors:
  • For MCP CLI: Use --with-editable . to install local dependencies
  • For manual setup: Run pip install -r requirements.txt
• Permission errors: Use absolute paths in configuration
• Environment variables not working: Verify .env file format or -v flag syntax
• Module not found: Ensure you're using --with-editable . flag for local package installation

Debugging Steps

Step 1: Check MCP CLI Status

Step 2: Test Server Manually

Step 3: Check Configuration

For Claude Desktop:

For Claude Code:

Step 3.5: Fix Path Issues (Claude Code specific)

Step 4: Reinstall if Needed

For MCP CLI:

For Claude Code:

Common Error Messages

Manual Configuration Fallback

For Claude Desktop: If MCP CLI isn't working, add this to Claude Desktop config manually:

For Claude Code: If the claude mcp add command isn't working, you can use the JSON format with absolute paths:

Example of correct Claude Code configuration (with absolute paths):

Connection Issues

• Chrome won't start: The MCP server will start Chrome automatically when you use start_chrome()
• Can't connect: Try get_connection_status() to check the connection
• Tools not working: Ensure you've called connect_to_browser() or used start_chrome_and_connect()

Common Misconceptions

• This is not a web server: The MCP server runs inside Claude Desktop, not as a separate web service
• No separate installation needed: Once configured in Claude Desktop, the server starts automatically
• Your app runs separately: This tool connects to your existing web application, it doesn't run it

Development & Testing

This section is for developers who want to test or modify the MCP server itself.

Development Setup

With uv (recommended):

With pip:

Code Quality Tools

Building the Extension

Install DXT packaging tools:

Build the extension:

Using Makefile for development:

Pre-commit Hooks

This project uses pre-commit hooks to ensure code quality:

• ruff: Linting and formatting
• mypy: Type checking
• pytest: Test validation
• MCP validation: Server registration check

Pre-commit hooks run automatically on git commit and can be run manually with make pre-commit.

License

MIT License