Chrome DevTools MCP

Chrome DevTools MCP brings the full power of Chrome DevTools to AI coding agents. By exposing browser automation, debugging, and performance capabilities through the Model Context Protocol, it enables AI assistants to interact with live web pages in powerful ways.

What It Does

Browser Automation

Control Chrome programmatically:

• Navigation: Open pages, go back/forward, wait for elements
• Interaction: Click, type, hover, drag, scroll
• Forms: Fill inputs, handle dialogs, upload files
• Multi-tab: Manage multiple browser tabs

Performance Analysis

Leverage Chrome’s built-in performance tools:

• Performance Tracing: Record and analyze page performance
• CrUX Integration: Get real-user experience data
• Metrics: Core Web Vitals, loading times, rendering performance

Debugging Capabilities

Deep browser inspection:

• Network Monitoring: Track all network requests
• Console Access: Read console messages with source-mapped stack traces
• JavaScript Evaluation: Run code in page context
• Screenshots: Capture visual state of pages

Key Features

1. Reliable Automation

Unlike screenshot-based approaches, Chrome DevTools MCP uses the actual DevTools Protocol:

• Deterministic: No ambiguity in element targeting
• Fast: Direct protocol communication
• Robust: Automatic waiting for elements and states

2. Performance Insights

Get actionable performance data:

• Lab Data: Chrome’s performance metrics from tracing
• Field Data: Real-user experience from CrUX
• Recommendations: Actionable improvement suggestions

3. Advanced Debugging

Powerful debugging for AI-assisted development:

• Network Inspection: Monitor all HTTP requests
• Console Logs: Access console with proper source maps
• JavaScript Execution: Run and evaluate code
• Page Snapshots: Get complete accessibility tree

Tools Overview

Input Automation (8 tools)

• click - Click on page elements
• drag - Drag and drop operations
• fill - Fill form fields
• fill_form - Fill multiple form fields
• handle_dialog - Handle alert/prompt/confirm dialogs
• hover - Hover over elements
• press_key - Press keyboard keys
• upload_file - Upload files to file inputs

Navigation (6 tools)

• close_page - Close the current page
• list_pages - List all open pages
• navigate_page - Navigate to a URL
• new_page - Open a new page/tab
• select_page - Switch between tabs
• wait_for - Wait for conditions

Emulation (2 tools)

• emulate - Emulate devices/geolocations
• resize_page - Resize viewport

Performance (3 tools)

• performance_analyze_insight - Get performance recommendations
• performance_start_trace - Start performance tracing
• performance_stop_trace - Stop and analyze tracing

Network (2 tools)

• get_network_request - Get details of a specific request
• list_network_requests - List all network requests

Debugging (5 tools)

• evaluate_script - Evaluate JavaScript in page context
• get_console_message - Get recent console messages
• list_console_messages - List all console messages
• take_screenshot - Take a screenshot
• take_snapshot - Take an accessibility snapshot

Installation

Quick Setup

```json { “mcpServers”: { “chrome-devtools”: { “command”: “npx”, “args”: [“-y”, “chrome-devtools-mcp@latest”] } } } ```

Claude Code

```bash claude mcp add chrome-devtools —scope user npx chrome-devtools-mcp@latest ```

Cursor

Click the install button or add manually:

• Settings → MCP → New MCP Server
• Use command: `npx -y chrome-devtools-mcp@latest`

VS Code

```bash code —add-mcp ’{“name”:“io.github.ChromeDevTools/chrome-devtools-mcp”,“command”:“npx”,“args”:[“-y”,“chrome-devtools-mcp”],“env”:{}}’ ```

Configuration Options

Basic Options

Option	Description	Default
`—headless`	Run without UI	false
`—channel`	Chrome channel (stable/canary/beta/dev)	stable
`—executable-path`	Custom Chrome path	Auto-detected

Connection Options

Option	Description
`—browser-url`	Connect to running Chrome (e.g., http://127.0.0.1:9222)
`—wsEndpoint`	WebSocket endpoint for Chrome connection
`—wsHeaders`	Custom headers for WebSocket (JSON format)

Browser Profile

Option	Description
`—user-data-dir`	Chrome profile directory
`—isolated`	Use temporary profile (auto-cleanup)

Feature Toggles

Option	Description	Default
`—category-emulation`	Enable emulation tools	true
`—category-performance`	Enable performance tools	true
`—category-network`	Enable network tools	true
`—performance-crux`	Fetch CrUX data	true
`—usage-statistics`	Send anonymous usage stats	true

Example Configuration

```json { “mcpServers”: { “chrome-devtools”: { “command”: “npx”, “args”: [ “chrome-devtools-mcp@latest”, “—channel=canary”, “—headless=true”, “—isolated=true”, “—viewport=1280x720” ] } } } ```

Connecting to Running Chrome

Option 1: Auto-Connect (Chrome 144+)

1. Navigate to `chrome://inspect/#remote-debugging`
2. Enable remote debugging
3. Configure MCP with `—autoConnect`

```json { “mcpServers”: { “chrome-devtools”: { “command”: “npx”, “args”: [“chrome-devtools-mcp@latest”, “—autoConnect”] } } } ```

Option 2: Manual Port Forwarding

Start Chrome with remote debugging:

```bash

macOS

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome
—remote-debugging-port=9222
—user-data-dir=/tmp/chrome-profile

Linux

google-chrome —remote-debugging-port=9222 —user-data-dir=/tmp/chrome-profile

Windows

“C:\Program Files\Google\Chrome\Application\chrome.exe”
—remote-debugging-port=9222
—user-data-dir=“%TEMP%\chrome-profile” ```

Configure MCP to connect:

```json { “mcpServers”: { “chrome-devtools”: { “command”: “npx”, “args”: [ “chrome-devtools-mcp@latest”, “—browser-url=http://127.0.0.1:9222” ] } } } ```

Usage Examples

Check Website Performance

``` Check the performance of https://developers.chrome.com ```

This will:

1. Open Chrome to the specified URL
2. Record a performance trace
3. Analyze and provide insights

Automate Form Submission

```typescript // Navigate to form page await navigate_page({ url: “https://example.com/form” });

// Wait for form to load await wait_for({ text: “Submit” });

// Fill form fields await fill_form({ fields: [ { name: “email”, value: “user@example.com” }, { name: “password”, value: “secure-password” } ] });

// Click submit await click({ ref: “submit-button-ref” }); ```

Debug JavaScript Error

```typescript // Navigate to problematic page await navigate_page({ url: “https://example.com/page-with-error” });

// Get console messages const errors = await list_console_messages({ level: “error” });

// Evaluate JavaScript to get more info const pageState = await evaluate_script({ function: ”() => ({ title: document.title, url: window.location.href })” }); ```

Take Visual Snapshot

```typescript // Get accessibility snapshot const snapshot = await take_snapshot();

// Take screenshot await take_screenshot({ filename: “page-screenshot.png” }); ```

Browser Support

Browser	Support Level
Chrome	Full support
Chromium	Full support
Edge (Chromium)	Full support
Firefox	Not supported
Safari	Not supported

Privacy & Security

Data Exposure

⚠️ Important: Chrome DevTools MCP exposes browser content to MCP clients:

• All page content is accessible
• Console messages are readable
• Network requests are visible
• Cookies and storage are accessible

Recommendation: Avoid sharing sensitive information while using MCP.

Usage Statistics

• Opt-in: Default is enabled, can be disabled with `—no-usage-statistics`
• What Google Collectes: Tool success rates, latency, environment info
• Independent: Separate from Chrome browser’s usage statistics

Security Best Practices

1. Use Isolated Profile: `—isolated` creates temporary profiles
2. Limit Access: Use `—allowed-hosts` for production
3. HTTPS Only: Prefer HTTPS connections when possible
4. Review Permissions: Regularly audit MCP server permissions

Troubleshooting

Common Issues

Chrome Won’t Start

``` Error: Chrome failed to start ```

Solutions:

• Ensure Chrome/Chromium is installed
• Check `—executable-path` configuration
• Try `—headless=true`
• Review logs with `—logFile`

Connection Timeout

``` Error: Connection timeout ```

Solutions:

• Verify Chrome is running with remote debugging
• Check `—browser-url` port matches
• Firewall settings on port 9222

Sandbox Issues

``` Error: Sandbox failed to initialize ```

Solutions:

• Disable sandbox: `—no-sandbox`
• Run Chrome with `—disable-setuid-sandbox`
• Configure MCP client to exclude from sandbox

Debug Mode

Run with verbose logging:

```bash DEBUG=* npx chrome-devtools-mcp@latest ```

Logs are written to:

• Linux/macOS: `~/.cache/chrome-devtools-mcp/logs/`
• Windows: `%USERPROFILE%/.cache/chrome-devtools-mcp/logs/`

Performance Optimization

Recommended Settings

Scenario	Headless	Viewport	Channel
CI/CD	true	1280x720	stable
Development	false	auto	canary
Quick Tests	true	1920x1080	stable

Tips

1. Use `—isolated` for clean state between runs
2. Limit Features: Disable unused categories with `—category-*`
3. Reuse Connections: Keep browser running between tasks
4. Set Viewport: Define fixed viewport for consistent results

Comparison with Playwright MCP

Feature	Chrome DevTools MCP	Playwright MCP
Browser	Chrome/Chromium only	All browsers
Performance	Built-in Chrome tracing	Playwright tracing
Ease of Setup	Simpler (Chrome usually installed)	Requires Playwright browsers
Reliability	Direct protocol	Cross-browser abstraction
Best For	Chrome-specific tasks	Cross-browser testing

Resources

• GitHub: https://github.com/ChromeDevTools/chrome-devtools-mcp
• Tool Reference: /docs/tool-reference.md
• Chrome DevTools: https://developer.chrome.com/docs/devtools/
• Troubleshooting: /docs/troubleshooting.md
• Design Principles: /docs/design-principles.md

Summary

Chrome DevTools MCP empowers AI coding agents with comprehensive browser automation and debugging capabilities. By leveraging Chrome’s native DevTools Protocol, it provides reliable, deterministic interactions with web pages. Whether you need performance analysis, automated testing, or interactive debugging, Chrome DevTools MCP offers a powerful bridge between AI assistants and live browser environments.