Chrome DevTools MCP server for AI agents

Chrome DevTools MCP server provides a bridge between Claude and Chrome's debugging capabilities, allowing you to connect to any web application running in Chrome for debugging network requests, console errors, and performance issues, all through natural conversation with Claude.

Installation Options

Option 1: Claude Desktop Extension (Easiest)

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

Option 2: MCP CLI (Advanced)

Quick Install (most common):

git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp
mcp install server.py -n "Chrome DevTools MCP" --with-editable .

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

All Installation Options:

# Clone the repository
git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp

# Basic installation with local dependencies
mcp install server.py --with-editable .

# Install with custom name
mcp install server.py -n "Chrome DevTools MCP" --with-editable .

# Install with environment variables
mcp install server.py -n "Chrome DevTools MCP" --with-editable . -v CHROME_DEBUG_PORT=9222

# Install with additional packages if needed
mcp install server.py -n "Chrome DevTools MCP" --with-editable . --with websockets --with aiohttp

# Install with environment file (copy .env.example to .env first)
cp .env.example .env
# Edit .env with your settings
mcp install server.py -n "Chrome DevTools MCP" --with-editable . -f .env

Option 3: Claude Code Integration

Clone this repository

git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp

Install dependencies with UV (creates venv)

uv sync  # Creates .venv and installs dependencies

Add MCP server using Claude CLI with absolute paths

# Get the absolute paths
SERVER_PATH="$(pwd)/server.py"
PYTHON_PATH="$(pwd)/.venv/bin/python"

# Add the server with absolute paths
claude mcp add chrome-devtools "$PYTHON_PATH" "$SERVER_PATH" -e CHROME_DEBUG_PORT=9222

Verify installation

# List configured MCP servers
claude mcp list

# Get details about the server (check that paths are absolute)
claude mcp get chrome-devtools

Option 4: Manual Claude Desktop Setup

Clone this repository

git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp

Install dependencies

uv sync

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

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "python",
      "args": ["/absolute/path/to/chrome-devtools-mcp/server.py"],
      "env": {
        "CHROME_DEBUG_PORT": "9222"
      }
    }
  }
}

Restart Claude Desktop

Verify Installation

After installation, verify the server is available:

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

Quick Start

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

Debug Your Web Application

One-step setup (recommended):

start_chrome_and_connect("localhost:3000")

Replace localhost:3000 with your application's URL

If Chrome isn't found automatically:

start_chrome_and_connect("localhost:3000", chrome_path="/path/to/chrome")

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_chrome()
navigate_to_url("localhost:3000")
connect_to_browser()

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

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

Use Cases

Debugging API Calls in Your Web Application

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

Example workflow:

You: "I need to debug my React app at localhost:3000"
Claude: I'll start Chrome with debugging enabled and navigate to your app.

start_chrome_and_connect("localhost:3000")

Perfect! Chrome is now running with debugging enabled and connected to your app. Let me check for any failed network requests:

get_network_requests(filter_status=500)

I can see there are 3 failed requests to your API. Let me get the details of the first one:

get_network_response("request-123")

Checking JavaScript Console Errors

When your web application has JavaScript errors or unexpected behaviour:

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

Performance Debugging

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

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

Common Commands

Task	Command
Start Chrome and connect to app	`start_chrome_and_connect("localhost:3000")`
Start Chrome (manual setup)	`start_chrome()`
Navigate to page	`navigate_to_url("localhost:3000")`
Connect to browser	`connect_to_browser()`
See all network requests	`get_network_requests()`
Find failed API calls	`get_network_requests(filter_status=404)`
Check for JavaScript errors	`get_console_error_summary()`
Watch console in real-time	`monitor_console_live(10)`
Check page load performance	`get_page_info()`
Examine a variable	`inspect_console_object("window.myApp")`
View cookies	`get_cookies()`
Run JavaScript	`execute_javascript("document.title")`

Troubleshooting

Server Shows as "Disabled" in Claude Desktop

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

Check Claude Desktop logs:
- macOS: ~/Library/Logs/Claude/mcp*.log
- Windows: %APPDATA%/Claude/logs/mcp*.log

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

Check dependencies:

# Ensure all dependencies are available
pip install mcp websockets aiohttp

# Test imports
python3 -c "from server import mcp; print('OK')"

Restart Claude Desktop completely (quit and reopen)

Common Error Messages

Error	Solution
"Module not found"	Use `--with-editable .` flag
"No server object found"	Server should export `mcp` object (already fixed)
"Import error"	Check `pip install mcp websockets aiohttp`
"Permission denied"	Use absolute paths in config
"Server disabled"	Check Claude Desktop logs, restart Claude
"python: command not found" (Claude Code)	Use absolute path to venv Python: `/path/to/.venv/bin/python`
"server.py: No such file" (Claude Code)	Use absolute path to server: `/path/to/server.py`
"ModuleNotFoundError" (Claude Code)	Use venv Python that has dependencies installed

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()

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "chrome-devtools" '{"command":"python","args":["/absolute/path/to/chrome-devtools-mcp/server.py"],"env":{"CHROME_DEBUG_PORT":"9222"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "chrome-devtools": {
            "command": "python",
            "args": [
                "/absolute/path/to/chrome-devtools-mcp/server.py"
            ],
            "env": {
                "CHROME_DEBUG_PORT": "9222"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "chrome-devtools": {
            "command": "python",
            "args": [
                "/absolute/path/to/chrome-devtools-mcp/server.py"
            ],
            "env": {
                "CHROME_DEBUG_PORT": "9222"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect