Skip to content

README.md

Latest commit

 

History

History
378 lines (271 loc) · 14 KB

README.md

File metadata and controls

378 lines (271 loc) · 14 KB

Chrome DevTools MCP

npm chrome-devtools-mcp package

chrome-devtools-mcp empowers your AI coding assistant (like Gemini, Claude, Cursor, or Copilot) to control and inspect a live Chrome browser. It acts as a Model-Context-Protocol (MCP) server, giving your agent access to the full power of Chrome DevTools for reliable automation, in-depth debugging, and performance analysis.

This means you can ask your AI assistant to perform tasks like:

  • "Analyze the performance of my web app and suggest improvements."
  • "Navigate to the login page, fill in the form with test credentials, and take a screenshot of the dashboard."
  • "Debug the console errors on this page and tell me what's wrong."

Table of Contents

Key Features

  • Reliable Automation: Uses Puppeteer to automate actions in Chrome, automatically waiting for actions to complete and the page to be ready for the next command.
  • Powerful Debugging: Inspect the DOM, analyze network requests, check the browser console, and take screenshots.
  • Performance Insights: Leverages Chrome DevTools to record performance traces and extract actionable insights to help you improve your web application's performance.
  • Multi-Page Support: Manage multiple browser tabs, switch between them, and perform actions on specific pages.
  • Extensive Toolset: A rich set of tools for everything from simple clicks to complex performance analysis.

Getting Started

Prerequisites

  • Node.js v20.19 or a newer LTS version.
  • Google Chrome (Stable channel recommended).
  • An AI coding assistant that supports the Model-Context-Protocol (MCP).

Installation

The easiest way to use chrome-devtools-mcp is to configure your MCP client to use npx. This ensures you are always using the latest version.

Add the following configuration to your MCP client:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}
Click here for instructions for your specific MCP client
Claude Code Use the Claude Code CLI to add the Chrome DevTools MCP server (guide): 
claude mcp add chrome-devtools npx chrome-devtools-mcp@latest
Cline Follow https://docs.cline.bot/mcp/configuring-mcp-servers and use the config provided above.
Codex Follow the configure MCP guide using the standard config from above. You can also install the Chrome DevTools MCP server using the Codex CLI: 
codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest

On Windows 11

Configure the Chrome install location and increase the startup timeout by updating .codex/config.toml and adding the following env and startup_timeout_ms parameters:

[mcp_servers.chrome-devtools]
command = "cmd"
args = [
    "/c",
    "npx",
    "-y",
    "chrome-devtools-mcp@latest",
]
env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }
startup_timeout_ms = 20_000
Copilot CLI

Start Copilot CLI:

copilot

Start the dialog to add a new MCP server by running:

/mcp add

Configure the following fields and press CTR-S to save the configuration:

  • Server name: chrome-devtools
  • Server Type: [1] Local
  • Command: npx
  • Arguments: -y, chrome-devtools-mcp@latest
Copilot / VS Code Follow the MCP install guide, with the standard config from above. You can also install the Chrome DevTools MCP server using the VS Code CLI: 
```bash
code --add-mcp '{"name":"chrome-devtools","command":"npx","args":["chrome-devtools-mcp@latest"]}'
```
Cursor

Click the button to install:

Install in Cursor

Or install manually:

Go to Cursor Settings -> MCP -> New MCP Server. Use the config provided above.

Gemini CLI Install the Chrome DevTools MCP server using the Gemini CLI.

Project wide:

gemini mcp add chrome-devtools npx chrome-devtools-mcp@latest

Globally:

gemini mcp add -s user chrome-devtools npx chrome-devtools-mcp@latest

Alternatively, follow the MCP guide and use the standard config from above.

Gemini Code Assist Follow the configure MCP guide using the standard config from above.
JetBrains AI Assistant & Junie

Go to Settings | Tools | AI Assistant | Model Context Protocol (MCP) -> Add. Use the config provided above. The same way chrome-devtools-mcp can be configured for JetBrains Junie in Settings | Tools | Junie | MCP Settings -> Add. Use the config provided above.

Visual Studio 
**Click the button to install:**

[<img src="https://img.shields.io/badge/Visual_Studio-Install-C16FDE?logo=visualstudio&logoColor=white" alt="Install in Visual Studio">](https://vs-open.link/mcp-install?%7B%22name%22%3A%22chrome-devtools%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22chrome-devtools-mcp%40latest%22%5D%7D)
Warp

Go to Settings | AI | Manage MCP Servers -> + Add to add an MCP Server. Use the config provided above.

Your First Prompt

To check if everything is working, enter the following prompt in your MCP client:

@chrome-devtools Check the performance of https://developers.chrome.com

Your MCP client should open a Chrome browser window and record a performance trace.

Note

The MCP server will start the browser automatically when you use a tool that requires a running browser instance. Simply connecting to the server won't start the browser.

Usage Examples

Here are a few examples of what you can do with chrome-devtools-mcp.

Analyze Website Performance

Prompt:

@chrome-devtools Start a performance trace of https://pptr.dev, then stop the trace and give me a summary of the performance insights.

This will navigate to the Puppeteer documentation website, record a performance trace, and provide a summary of potential performance issues and Core Web Vitals.

Automate Form Submission

Prompt:

@chrome-devtools Navigate to https://www.google.com, take a snapshot of the page, then use the snapshot to fill the search box with "puppeteer" and click the "Google Search" button.

This demonstrates how to automate form submissions by first inspecting the page structure and then using the element UIDs to interact with them.

Debugging a Web Page

Prompt:

@chrome-devtools Navigate to https://angular.io/ and list any console errors. Then take a full-page screenshot and save it to a file named 'angular-home.png'.

This is useful for quickly identifying client-side errors and capturing the state of the page for further analysis.

Tools Reference

For a detailed list of all available tools and their parameters, please see the Tool Reference.

Configuration

You can customize the behavior of chrome-devtools-mcp by passing command-line arguments.

  • --browserUrl, -u Connect to a running Chrome instance using port forwarding. For more details see: https://developer.chrome.com/docs/devtools/remote-debugging/local-server.

    • Type: string

  • --headless Whether to run in headless (no UI) mode.

    • Type: boolean
    • Default: false

  • --executablePath, -e Path to custom Chrome executable.

    • Type: string

  • --isolated If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed.

    • Type: boolean
    • Default: false

  • --channel Specify a different Chrome channel that should be used. The default is the stable channel version.

    • Type: string
    • Choices: stable, canary, beta, dev

  • --logFile Path to a file to write debug logs to. Set the env variable DEBUG to * to enable verbose logs. Useful for submitting bug reports.

    • Type: string

  • --viewport Initial viewport size for the Chrome instances started by the server. For example, 1280x720

    • Type: string

  • --proxyServer Proxy server configuration for Chrome passed as --proxy-server when launching the browser. See https://www.chromium.org/developers/design-documents/network-settings/ for details.

    • Type: string

  • --acceptInsecureCerts If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.

    • Type: boolean

Pass them via the args property in your MCP client's JSON configuration. For example:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--channel=canary",
        "--headless=true",
        "--isolated=true"
      ]
    }
  }
}

You can also run npx chrome-devtools-mcp@latest --help to see all available configuration options.

How It Works

chrome-devtools-mcp is a server that implements the Model-Context-Protocol (MCP). It uses Puppeteer to launch and control a Chrome browser instance. When your AI assistant calls a tool, the MCP server translates that request into a series of Puppeteer commands that are executed in the browser. The results are then formatted and sent back to the assistant.

By default, chrome-devtools-mcp starts a Chrome instance using a dedicated user data directory to avoid interfering with your personal browsing profile. This directory is located at:

  • Linux / macOS: $HOME/.cache/chrome-devtools-mcp/chrome-profile-$CHANNEL
  • Windows: %HOMEPATH%/.cache/chrome-devtools-mcp/chrome-profile-$CHANNEL

You can use the --isolated flag to create a temporary user data directory that is cleaned up after the browser is closed.

Troubleshooting

If you encounter any issues, please refer to our Troubleshooting Guide.

Contributing

We welcome contributions! Please see our Contributing Guide for more details.

Disclaimer

chrome-devtools-mcp exposes the content of the browser instance to the MCP clients, allowing them to inspect, debug, and modify any data in the browser or DevTools. Avoid sharing sensitive or personal information that you don't want to share with MCP clients.