chrome-devtools-mcp Documentation

Chrome DevTools for coding agents

49,052 stars TypeScript TypeScript 1 file · ~20,871 tokens #browser#chrome#chrome-devtools#debugging#devtools#mcp#mcp-server#puppeteer
RAW Doc

File: README.md

Chrome DevTools for agents

Chrome DevTools for agents (chrome-devtools-mcp) lets your coding agent (such as Antigravity, Claude, Cursor or Copilot)
control and inspect a live Chrome browser. It acts as a Model-Context-Protocol
(MCP) server, giving your AI coding assistant access to the full power of
Chrome DevTools for reliable automation, in-depth debugging, and performance analysis.
A CLI is also provided for use without MCP.

[Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md) | [Design Principles](./docs/design-principles.md)

Key features

  • Get performance insights: Uses Chrome
    DevTools     to record
    traces and extract actionable performance insights.
  • Advanced browser debugging: Analyze network requests, take screenshots and
    check browser console messages (with source-mapped stack traces).
  • Reliable automation. Uses
    puppeteer to automate actions in
    Chrome and automatically wait for action results.

Disclaimers

chrome-devtools-mcp exposes 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.

chrome-devtools-mcp officially supports Google Chrome and Chrome for Testing only.
Other Chromium-based browsers may work, but this is not guaranteed, and you may encounter unexpected behavior. Use at your own discretion.
We are committed to providing fixes and support for the latest version of Extended Stable Chrome.

Performance tools may send trace URLs to the Google CrUX API to fetch real-user
experience data. This helps provide a holistic performance picture by
presenting field data alongside lab data. This data is collected by the Chrome
User Experience Report (CrUX). To disable
this, run with the --no-performance-crux flag.

**Usage statistics**

Google collects usage statistics (such as tool invocation success rates, latency, and environment information) to improve the reliability and performance of Chrome DevTools MCP.

Data collection is enabled by default. You can opt-out by passing the --no-usage-statistics flag when starting the server:

json
"args": ["-y", "chrome-devtools-mcp@latest", "--no-usage-statistics"]

Google handles this data in accordance with the Google Privacy Policy.

Google's collection of usage statistics for Chrome DevTools MCP is independent from the Chrome browser's usage statistics. Opting out of Chrome metrics does not automatically opt you out of this tool, and vice-versa.

Collection is disabled if CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS or CI env variables are set.

Update checks

By default, the server periodically checks the npm registry for updates and logs a notification when a newer version is available.
You can disable these update checks by setting the CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS environment variable.

Requirements

Getting started

Add the following config to your MCP client:

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

[!NOTE]
Using chrome-devtools-mcp@latest ensures that your MCP client will always use the latest version of the Chrome DevTools MCP server.

If you are interested in doing only basic browser tasks, use the --slim mode:

json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest", "--slim", "--headless"]
    }
  }
}

See Slim tool reference.

MCP Client configuration

Amp
Follow https://ampcode.com/manual#mcp and use the config provided above. You can also install the Chrome DevTools MCP server using the CLI:

bash
amp mcp add chrome-devtools -- npx chrome-devtools-mcp@latest

Antigravity

To use the Chrome DevTools MCP server follow the instructions from Antigravity's docs to install a custom MCP server. Add the following config to the MCP servers config:

bash
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--browser-url=http://127.0.0.1:9222"
      ]
    }
  }
}

This will make the Chrome DevTools MCP server automatically connect to the browser that Antigravity is using. If you are not using port 9222, make sure to adjust accordingly.

Chrome DevTools MCP will not start the browser instance automatically using this approach because the Chrome DevTools MCP server connects to Antigravity's built-in browser. If the browser is not already running, you have to start it first by clicking the Chrome icon at the top right corner.

Bob

Follow the IBM Bob MCP guide and add the Chrome DevTools MCP server to your Bob MCP configuration. Use the global config (~/.bob/mcp.json) to apply it across all workspaces, or a project config (.bob/mcp.json) to scope it to one project:

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

You can edit these files from Bob panel → Settings → MCP → Edit Global MCP (or Edit Project MCP). Bob hot-reloads on save. Once the server appears in the MCP tab, switch to the 🌎 Browser Dev mode to get guided browser debugging directly in Bob.

Claude Code

Install via CLI (MCP only)

Use the Claude Code CLI to add the Chrome DevTools MCP server (guide):

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

Install as a Plugin (MCP + Skills)

[!NOTE]
If you already had Chrome DevTools MCP installed previously for Claude Code, make sure to remove it first from your installation and configuration files.

To install Chrome DevTools MCP with skills, add the marketplace registry in Claude Code:

sh
/plugin marketplace add ChromeDevTools/chrome-devtools-mcp

Then, install the plugin:

sh
/plugin install chrome-devtools-mcp@chrome-devtools-plugins

Restart Claude Code to have the MCP server and skills load (check with /skills).

[!TIP]
If the plugin installation fails with a Failed to clone repository error (e.g., HTTPS connectivity issues behind a corporate firewall), see the troubleshooting guide for workarounds, or use the CLI installation method above instead.

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:

bash
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:

text
[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

Command Code

Use the Command Code CLI to add the Chrome DevTools MCP server (MCP guide):

bash
cmd mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest

Copilot CLI

Start Copilot CLI:

text
copilot

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

text
/mcp add

Configure the following fields and press CTRL+S to save the configuration:

  • Server name: chrome-devtools

  • Server Type: [1] Local

  • Command: npx -y chrome-devtools-mcp@latest

    Copilot / VS Code

Install as a Plugin (Recommended)

The easiest way to get up and running is to install chrome-devtools-mcp as an agent plugin.
This bundles the MCP server and all skills together, so your agent gets both the tools
and the expert guidance it needs to use them effectively.

  1. Open the Command Palette (Cmd+Shift+P on macOS or Ctrl+Shift+P on Windows/Linux).
  2. Search for and run the Chat: Install Plugin From Source command.
  3. Paste in our repository name: ChromeDevTools/chrome-devtools-mcp.

That's it! Your agent is now supercharged with Chrome DevTools capabilities.

Install as an MCP Server (MCP only)

Click the button to install:

Or install manually:

Follow the VS Code MCP configuration guide using the standard config from above, or use the CLI:

For macOS and Linux:

bash
code --add-mcp '{"name":"io.github.ChromeDevTools/chrome-devtools-mcp","command":"npx","args":["-y","chrome-devtools-mcp"],"env":{}}'

For Windows (PowerShell):

powershell
code --add-mcp '{"""name""":"""io.github.ChromeDevTools/chrome-devtools-mcp""","""command""":"""npx""","""args""":["""-y""","""chrome-devtools-mcp"""]}'

Cursor

Click the button to install:

Or install manually:

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

Devin CLI

Install via CLI (MCP only)

Use the Devin CLI to add the Chrome DevTools MCP server (guide):

bash
devin mcp add chrome-devtools -- npx chrome-devtools-mcp@latest

Factory CLI
Use the Factory CLI to add the Chrome DevTools MCP server (guide):

bash
droid mcp add chrome-devtools "npx -y chrome-devtools-mcp@latest"

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

Project wide:

bash
# Either MCP only:
gemini mcp add chrome-devtools npx chrome-devtools-mcp@latest
# Or as a Gemini extension (MCP+Skills):
gemini extensions install --auto-update https://github.com/ChromeDevTools/chrome-devtools-mcp

Globally:

bash
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.

Grok Build CLI

bash
grok mcp add chrome-devtools npx chrome-devtools-mcp@latest

See the docs for more options

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.

Kiro

In Kiro Settings, go to Configure MCP > Open Workspace or User MCP Config > Use the configuration snippet provided above.

Or, from the IDE Activity Bar > Kiro > MCP Servers > Click Open MCP Config. Use the configuration snippet provided above.

Katalon Studio

The Chrome DevTools MCP server can be used with Katalon StudioAssist via an MCP proxy.

Step 1: Install the MCP proxy by following the MCP proxy setup guide.

Step 2: Start the Chrome DevTools MCP server with the proxy:

bash
mcp-proxy --transport streamablehttp --port 8080 -- npx -y chrome-devtools-mcp@latest

Note: You may need to pick another port if 8080 is already in use.

Step 3: In Katalon Studio, add the server to StudioAssist with the following settings:

  • Connection URL: http://127.0.0.1:8080/mcp
  • Transport type: HTTP

Once connected, the Chrome DevTools MCP tools will be available in StudioAssist.

Mistral Vibe

Add in ~/.vibe/config.toml:

toml
[[mcp_servers]]
name = "chrome-devtools"
transport = "stdio"
command = "npx"
args = ["chrome-devtools-mcp@latest"]

OpenCode

Add the following configuration to your opencode.json file. If you don't have one, create it at ~/.config/opencode/opencode.json (guide):

json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "chrome-devtools": {
      "type": "local",
      "command": ["npx", "-y", "chrome-devtools-mcp@latest"]
    }
  }
}

Qoder

In Qoder Settings, go to MCP Server > + Add > Use the configuration snippet provided above.

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

Qoder CLI

Install the Chrome DevTools MCP server using the Qoder CLI (guide):

Project wide:

bash
qodercli mcp add chrome-devtools -- npx chrome-devtools-mcp@latest

Globally:

bash
qodercli mcp add -s user chrome-devtools -- npx chrome-devtools-mcp@latest

Visual Studio

Click the button to install:

Warp

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

Windsurf
Follow the configure MCP guide
using the standard config from above.

Your first prompt

Enter the following prompt in your MCP Client to check if everything is working:

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

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

[!NOTE]
The MCP server will start the browser automatically once the MCP client uses a tool that requires a running browser instance. Connecting to the Chrome DevTools MCP server on its own will not automatically start the browser.

Tools

If you run into any issues, checkout our troubleshooting guide.

Configuration

The Chrome DevTools MCP server supports the following configuration option:

  • --autoConnect/ --auto-connect
    If specified, automatically connects to a browser (Chrome 144+) running locally from the user data directory identified by the channel param (default channel is stable). Requires the remote debugging server to be started in the Chrome instance via chrome://inspect/#remote-debugging.

    • Type: boolean
    • Default: false

  • --browserUrl/ --browser-url, -u
    Connect to a running, debuggable Chrome instance (e.g. http://127.0.0.1:9222). For more details see: https://github.com/ChromeDevTools/chrome-devtools-mcp#connecting-to-a-running-chrome-instance.

    • Type: string
    • Default: false

  • --wsEndpoint/ --ws-endpoint, -w
    WebSocket endpoint to connect to a running Chrome instance (e.g., ws://127.0.0.1:9222/devtools/browser/). Alternative to --browserUrl.

    • Type: string
    • Default: false

  • --wsHeaders/ --ws-headers
    Custom headers for WebSocket connection in JSON format (e.g., '{"Authorization":"Bearer token"}'). Only works with --wsEndpoint.

    • Type: string
    • Default: false

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

    • Type: boolean
    • Default: false

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

    • Type: string
    • Default: false

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

    • Type: boolean
    • Default: false

  • --userDataDir/ --user-data-dir
    Path to the user data directory for Chrome. Default is $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE

    • Type: string
    • Default: false

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

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

  • --logFile/ --log-file
    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
    • Default: false

  • --viewport
    Initial viewport size for the Chrome instances started by the server. For example, 1280x720. In headless mode, max size is 3840x2160px.

    • Type: string
    • Default: false

  • --proxyServer/ --proxy-server
    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
    • Default: false

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

    • Type: boolean
    • Default: false

  • --experimentalPageIdRouting/ --experimental-page-id-routing
    Whether to expose pageId on page-scoped tools and route requests by page ID (useful for concurrent agent sessions).

    • Type: boolean
    • Default: false

  • --experimentalDevtools/ --experimental-devtools
    Whether to enable automation over DevTools targets

    • Type: boolean
    • Default: false

  • --experimentalVision/ --experimental-vision
    Whether to enable coordinate-based tools such as click_at(x,y). Usually requires a computer-use model able to produce accurate coordinates by looking at screenshots.

    • Type: boolean
    • Default: false

  • --memoryDebugging/ --memory-debugging, -experimentalMemory
    Whether to enable memory debugging tools.

    • Type: boolean
    • Default: false

  • --experimentalStructuredContent/ --experimental-structured-content
    Whether to output structured formatted content.

    • Type: boolean
    • Default: false

  • --experimentalIncludeAllPages/ --experimental-include-all-pages
    Whether to include all kinds of pages such as webviews or background pages as pages.

    • Type: boolean
    • Default: false

  • --experimentalScreencast/ --experimental-screencast
    Exposes experimental screencast tools (requires ffmpeg). Install ffmpeg https://www.ffmpeg.org/download.html and ensure it is available in the MCP server PATH.

    • Type: boolean
    • Default: false

  • --experimentalFfmpegPath/ --experimental-ffmpeg-path
    Path to ffmpeg executable for screencast recording.

    • Type: string
    • Default: false

  • --categoryExperimentalWebmcp/ --category-experimental-webmcp
    Set to true to enable debugging WebMCP tools. Requires Chrome 150+ with the following flag: --enable-features=WebMCP

    • Type: boolean
    • Default: false

  • --chromeArg/ --chrome-arg
    Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.

    • Type: array
    • Default: false

  • --blockedUrlPattern/ --blocked-url-pattern
    Restricts browser's network access by blocking specified URL patterns (uses https://urlpattern.spec.whatwg.org/). Silently detaches from targets with blocked URLs upon connection, and blocks runtime requests (including navigations and subresources). Accepts an array of patterns.

    • Type: array
    • Default: false

  • --allowedUrlPattern/ --allowed-url-pattern
    Restricts browser's network access by allowing only specified URL patterns (uses https://urlpattern.spec.whatwg.org/). Requires Chrome 149+. Silently detaches from targets with unallowed URLs upon connection, and blocks runtime requests (including navigations and subresources). Accepts an array of patterns.

    • Type: array
    • Default: false

  • --ignoreDefaultChromeArg/ --ignore-default-chrome-arg
    Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.

    • Type: array
    • Default: false

  • --categoryEmulation/ --category-emulation
    Set to false to exclude tools related to emulation.

    • Type: boolean
    • Default: true

  • --categoryPerformance/ --category-performance
    Set to false to exclude tools related to performance.

    • Type: boolean
    • Default: true

  • --categoryNetwork/ --category-network
    Set to false to exclude tools related to network.

    • Type: boolean
    • Default: true

  • --categoryExtensions/ --category-extensions
    Set to true to include tools related to extensions. Note: This feature is currently only supported with a pipe connection. autoConnect, browserUrl, and wsEndpoint are not supported with this feature until 149 will be released.

    • Type: boolean
    • Default: false

  • --categoryExperimentalThirdParty/ --category-experimental-third-party
    Set to true to enable third-party developer tools exposed by the inspected page itself

    • Type: boolean
    • Default: false

  • --categoryPwa/ --category-pwa
    Set to true to include tools for automating Progressive Web Apps (install, launch, uninstall, and OS state). This feature is only supported with a pipe connection; autoConnect, browserUrl, and wsEndpoint are not supported.

    • Type: boolean
    • Default: false

  • --performanceCrux/ --performance-crux
    Set to false to disable sending URLs from performance traces to CrUX API to get field performance data.

    • Type: boolean
    • Default: true

  • --usageStatistics/ --usage-statistics
    Set to false to opt-out of usage statistics collection. Google collects usage data to improve the tool, handled under the Google Privacy Policy (https://policies.google.com/privacy). This is independent from Chrome browser metrics. Disabled if CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS or CI env variables are set.

    • Type: boolean
    • Default: true

  • --screenshotFormat/ --screenshot-format
    Override the default output format used by take_screenshot when the caller does not specify one. JPEG and WebP are ~3-5x smaller than PNG, which helps reduce context size in AI conversations. Unset preserves the existing default ("png").

    • Type: string
    • Choices: jpeg, png, webp
    • Default: false

  • --screenshotQuality/ --screenshot-quality
    Override the default compression quality (0-100) used by take_screenshot for JPEG and WebP when the caller does not specify one. Lower values mean smaller files. Ignored for PNG. Unset preserves the Puppeteer default.

    • Type: number
    • Default: false

  • --screenshotMaxWidth/ --screenshot-max-width
    Maximum width in pixels for screenshots. If the captured image is wider, it is downscaled (preserving aspect ratio) before being returned. Reduces context size in AI conversations. Unset means no resize.

    • Type: number
    • Default: false

  • --screenshotMaxHeight/ --screenshot-max-height
    Maximum height in pixels for screenshots. If the captured image is taller, it is downscaled (preserving aspect ratio) before being returned. Can be combined with --screenshot-max-width; the smaller scale factor wins. Unset means no resize.

    • Type: number
    • Default: false

  • --slim
    Exposes a "slim" set of 3 tools covering navigation, script execution and screenshots only. Useful for basic browser tasks.

    • Type: boolean
    • Default: false

  • --redactNetworkHeaders/ --redact-network-headers
    If true, redacts some of the network headers considered sensitive before returning to the client.

    • Type: boolean
    • Default: false

  • --allowUnrestrictedPaths/ --allow-unrestricted-paths
    If set, disables the default path restriction that applies when the MCP client does not negotiate the roots capability. By default, file-writing tools are restricted to the OS temp directory when no roots are configured. Use this only when connecting a trusted local client that does not implement MCP roots and requires access to paths outside the temp directory.

    • Type: boolean
    • Default: false

Pass them via the args property in the JSON configuration. For example:

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

Connecting via WebSocket with custom headers

You can connect directly to a Chrome WebSocket endpoint and include custom headers (e.g., for authentication):

json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--wsEndpoint=ws://127.0.0.1:9222/devtools/browser/",
        "--wsHeaders={\"Authorization\":\"Bearer YOUR_TOKEN\"}"
      ]
    }
  }
}

To get the WebSocket endpoint from a running Chrome instance, visit http://127.0.0.1:9222/json/version and look for the webSocketDebuggerUrl field.

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

Concepts

Concurrent sessions

Most MCP clients start one Chrome DevTools MCP server per conversation. If your
client shares a single server instance across concurrent agents or subagents,
start the server with --experimentalPageIdRouting. This exposes pageId on
page-scoped tools so each agent can route tool calls to the tab it is working
with.

json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--experimentalPageIdRouting"
      ]
    }
  }
}

If you run multiple independent MCP client sessions and want each session to
launch its own temporary Chrome profile, also pass --isolated. This avoids
sharing the default Chrome DevTools MCP user data directory between those
server instances.

User data directory

By default, chrome-devtools-mcp starts a Chrome's stable channel instance using the following user
data directory:

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

For non-stable channels, the channel name is appended to the directory name, for example
chrome-profile-canary.

The user data directory is not cleared between runs and is reused for subsequent
runs with the same channel. Only one browser can use it at a time. Set the isolated
option to true to use a temporary user data directory instead which will be cleared
automatically after the browser is closed.

Connecting to a running Chrome instance

By default, the Chrome DevTools MCP server will start a new Chrome instance with a dedicated profile. This might not be ideal in all situations:

  • If you would like to maintain the same application state when alternating between manual site testing and agent-driven testing.
  • When the MCP needs to sign into a website. Some accounts may prevent sign-in when the browser is controlled via WebDriver (the default launch mechanism for the Chrome DevTools MCP server).
  • If you're running your LLM inside a sandboxed environment, but you would like to connect to a Chrome instance that runs outside the sandbox.

In these cases, start Chrome first and let the Chrome DevTools MCP server connect to it. There are two ways to do so:

  • Automatic connection (available in Chrome 144): best for sharing state between manual and agent-driven testing.
  • Manual connection via remote debugging port: best when running inside a sandboxed environment.

Automatically connecting to a running Chrome instance

Step 1: Set up remote debugging in Chrome

In Chrome (>= M144), do the following to set up remote debugging:

  1. Navigate to chrome://inspect/#remote-debugging to enable remote debugging.
  2. Follow the dialog UI to allow or disallow incoming debugging connections.

Step 2: Configure Chrome DevTools MCP server to automatically connect to a running Chrome Instance

To connect the chrome-devtools-mcp server to the running Chrome instance, use
--autoConnect command line argument for the MCP server.

The following code snippet is an example configuration for gemini-cli:

json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest", "--autoConnect"]
    }
  }
}

Step 3: Test your setup

Make sure your browser is running. Open gemini-cli and run the following prompt:

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

[!NOTE]
The autoConnect option requires the user to start Chrome. If the user has multiple active profiles, the MCP server will connect to the default profile (as determined by Chrome). The MCP server has access to all open windows for the selected profile.

The Chrome DevTools MCP server will try to connect to your running Chrome
instance. It shows a dialog asking for user permission.

Clicking Allow results in the Chrome DevTools MCP server opening
developers.chrome.com and taking a performance
trace.

Manual connection using port forwarding

You can connect to a running Chrome instance by using the --browser-url option. This is useful if you are running the MCP server in a sandboxed environment that does not allow starting a new Chrome instance.

Here is a step-by-step guide on how to connect to a running Chrome instance:

Step 1: Configure the MCP client

Add the --browser-url option to your MCP client configuration. The value of this option should be the URL of the running Chrome instance. http://127.0.0.1:9222 is a common default.

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

Step 2: Start the Chrome browser

[!WARNING]
Enabling the remote debugging port opens up a debugging port on the running browser instance. Any application on your machine can connect to this port and control the browser. Make sure that you are not browsing any sensitive websites while the debugging port is open.

Start the Chrome browser with the remote debugging port enabled. Make sure to close any running Chrome instances before starting a new one with the debugging port enabled. The port number you choose must be the same as the one you specified in the --browser-url option in your MCP client configuration.

For security reasons, Chrome requires you to use a non-default user data directory when enabling the remote debugging port. You can specify a custom directory using the --user-data-dir flag. This ensures that your regular browsing profile and data are not exposed to the debugging session.

macOS

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

Linux

bash
/usr/bin/google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable

Windows

bash
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="%TEMP%\chrome-profile-stable"

Step 3: Test your setup

After configuring the MCP client and starting the Chrome browser, you can test your setup by running a simple prompt in your MCP client:

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

Your MCP client should connect to the running Chrome instance and receive a performance report.

If you hit VM-to-host port forwarding issues, see the “Remote debugging between virtual machine (VM) and host fails” section in docs/troubleshooting.md.

For more details on remote debugging, see the Chrome DevTools documentation.

Debugging Chrome on Android

Please consult these instructions.

Known limitations

See Troubleshooting.

Integrating as a browser subagent

If you are developing agentic tooling and want to provide an integrated browser subagent as part of your product, we recommend building on top of Chrome DevTools for agents.

For a reference implementation, see the Gemini CLI browser agent documentation.

File: docs/debugging-android.md

Experimental: Debugging Chrome on Android

This is an experimental feature as Puppeteer does not officially support Chrome on Android as a target.

The workflow below works for most users. See Troubleshooting: DevTools is not detecting the Android device for more help for more help.

  1. Open the Developer Options screen on your Android. See Configure on-device developer Options.
  2. Select Enable USB Debugging.
  3. Connect your Android device directly to your development machine using a USB cable.
  4. On your development machine setup port forwarding from your development machine to your android device:
    shell
    adb forward tcp:9222 localabstract:chrome_devtools_remote
  5. Configure your MCP server to connect to the Chrome
    json
    "chrome-devtools": {
  "command": "npx",
  "args": [
    "chrome-devtools-mcp@latest",
    "--wsEndpoint=ws://127.0.0.1:9222/devtools/browser/"
  ],
  "trust": true
}
  6. Test your setup by running the following prompt in your coding agent:
    none
    Check the performance of developers.chrome.com

The Chrome DevTools MCP server should now control Chrome on your Android device.

File: docs/design-principles.md

Design Principles

These are rough guidelines to follow when shipping features for the MCP server.
Apply them with nuance.

  • Agent-Agnostic API: Use standards like MCP. Don't lock in to one LLM. Interoperability is key.
  • Token-Optimized: Return semantic summaries. "LCP was 3.2s" is better than 50k lines of JSON. Files are the right location for large amounts of data.
  • Small, Deterministic Blocks: Give agents composable tools (Click, Screenshot), not magic buttons.
  • Self-Healing Errors: Return actionable errors that include context and potential fixes.
  • Human-Agent Collaboration: Output must be readable by machines (structured) AND humans (summaries).
  • Progressive Complexity: Tools should be simple by default (high-level actions) but offer advanced optional arguments for power users.
  • Reference over Value: for heavy assets (screenshots, traces, videos), return a file path or resource URI, never the raw data stream. Some MCP clients support a built-in handling of heavy assets e.g. directly displaying images. This could be an exception.

File: docs/tool-reference.md

Chrome DevTools MCP Tool Reference

Input automation

`click`

Description: Clicks on the provided element

Parameters:

  • uid (string) (required): The uid of an element on the page from the page content snapshot
  • dblClick (boolean) (optional): Set to true for double clicks. Default is false.
  • includeSnapshot (boolean) (optional): Whether to include a snapshot in the response. Default is false.

`drag`

Description: Drag an element onto another element

Parameters:

  • from_uid (string) (required): The uid of the element to drag
  • to_uid (string) (required): The uid of the element to drop into
  • includeSnapshot (boolean) (optional): Whether to include a snapshot in the response. Default is false.

`fill`

Description: Type text into an input, text area or select an option from a <select> element.

Parameters:

  • uid (string) (required): The uid of an element on the page from the page content snapshot
  • value (string) (required): The value to fill in. "true" or "false" for checkboxes and toggles, "true" for radio buttons.
  • includeSnapshot (boolean) (optional): Whether to include a snapshot in the response. Default is false.

`fill_form`

Description: Fill out multiple form elements (inputs, selects, checkboxes, radios) at once. ALWAYS prefer this tool over multiple individual 'fill' or 'click' calls when interacting with forms. It is significantly faster, more reliable, and reduces turn count. Example: Fill username, password, and check "Remember Me" in one call.

Parameters:

  • elements (array) (required): Elements from snapshot to fill out.
  • includeSnapshot (boolean) (optional): Whether to include a snapshot in the response. Default is false.

`handle_dialog`

Description: If a browser dialog was opened, use this command to handle it

Parameters:

  • action (enum: "accept", "dismiss") (required): Whether to dismiss or accept the dialog
  • promptText (string) (optional): Optional prompt text to enter into the dialog.

`hover`

Description: Hover over the provided element

Parameters:

  • uid (string) (required): The uid of an element on the page from the page content snapshot
  • includeSnapshot (boolean) (optional): Whether to include a snapshot in the response. Default is false.

`press_key`

Description: Press a key or key combination. Use this when other input methods like fill() cannot be used (e.g., keyboard shortcuts, navigation keys, or special key combinations).

Parameters:

  • key (string) (required): A key or a combination (e.g., "Enter", "Control+A", "Control++", "Control+Shift+R"). Modifiers: Control, Shift, Alt, Meta
  • includeSnapshot (boolean) (optional): Whether to include a snapshot in the response. Default is false.

`type_text`

Description: Type text using keyboard into a previously focused input

Parameters:

  • text (string) (required): The text to type
  • submitKey (string) (optional): Optional key to press after typing. E.g., "Enter", "Tab", "Escape"

`upload_file`

Description: Upload a file through a provided element.

Parameters:

  • filePaths (array) (required): One or more files paths to upload. File paths have to be local to the browser instance (not the MCP).
  • uid (string) (required): The uid of the file input element or an element that will open file chooser on the page from the page content snapshot
  • includeSnapshot (boolean) (optional): Whether to include a snapshot in the response. Default is false.

`click_at`

Description: Clicks at the provided coordinates (requires flag: --experimentalVision=true)

Parameters:

  • x (number) (required): The x coordinate
  • y (number) (required): The y coordinate
  • dblClick (boolean) (optional): Set to true for double clicks. Default is false.
  • includeSnapshot (boolean) (optional): Whether to include a snapshot in the response. Default is false.

`close_page`

Description: Closes the page by its index. The last open page cannot be closed.

Parameters:

  • pageId (number) (required): The ID of the page to close. Call list_pages to list pages.

`list_pages`

Description: Get a list of pages open in the browser.

Parameters: None

`navigate_page`

Description: Go to a URL, or back, forward, or reload. Use project URL if not specified otherwise.

Parameters:

  • handleBeforeUnload (enum: "accept", "dismiss") (optional): Whether to auto accept or beforeunload dialogs triggered by this navigation. Default is accept.
  • ignoreCache (boolean) (optional): Whether to ignore cache on reload.
  • initScript (string) (optional): A JavaScript script to be executed on each new document before any other scripts for the next navigation.
  • timeout (integer) (optional): Maximum wait time in milliseconds. If set to 0, the default timeout will be used.
  • type (enum: "url", "back", "forward", "reload") (optional): Navigate the page by URL, back or forward in history, or reload.
  • url (string) (optional): Target URL (only type=url)

`new_page`

Description: Open a new tab and load a URL. Use project URL if not specified otherwise.

Parameters:

  • url (string) (required): URL to load in a new page.
  • background (boolean) (optional): Whether to open the page in the background without bringing it to the front. Default is false (foreground).
  • isolatedContext (string) (optional): If specified, the page is created in an isolated browser context with the given name. Pages in the same browser context share cookies and storage. Pages in different browser contexts are fully isolated.
  • timeout (integer) (optional): Maximum wait time in milliseconds. If set to 0, the default timeout will be used.

`select_page`

Description: Select a page as a context for future tool calls.

Parameters:

  • pageId (number) (required): The ID of the page to select. Call list_pages to get available pages.
  • bringToFront (boolean) (optional): Whether to focus the page and bring it to the top.

`wait_for`

Description: Wait for the specified text to appear on the selected page.

Parameters:

  • text (array) (required): Non-empty list of texts. Resolves when any value appears on the page.
  • timeout (integer) (optional): Maximum wait time in milliseconds. If set to 0, the default timeout will be used.

Emulation

`emulate`

Description: Emulates various features on the selected page.

Parameters:

  • colorScheme (enum: "dark", "light", "auto") (optional): Emulate the dark or the light mode. Set to "auto" to reset to the default.
  • cpuThrottlingRate (number) (optional): Represents the CPU slowdown factor. Omit or set the rate to 1 to disable throttling
  • extraHttpHeaders (string) (optional): Extra HTTP headers as a JSON string object, e.g. {"X-Custom": "value", "Authorization": "Bearer token"}. Headers are included into every HTTP request originating from the page and persist across navigations until cleared. Pass an empty string to clear all extra headers.
  • geolocation (string) (optional): Geolocation (&lt;latitude&gt;,&lt;longitude&gt;) to emulate. Latitude between -90 and 90. Longitude between -180 and 180. Omit to clear the geolocation override.
  • networkConditions (enum: "Offline", "Slow 3G", "Fast 3G", "Slow 4G", "Fast 4G") (optional): Throttle network. Omit to disable throttling.
  • userAgent (string) (optional): User agent to emulate. Set to empty string to clear the user agent override.
  • viewport (string) (optional): Emulate device viewports '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to emulate mobile devices. 'landscape' to emulate landscape mode.

`resize_page`

Description: Resizes the selected page's window so that the page has specified dimension

Parameters:

  • height (number) (required): Page height
  • width (number) (required): Page width

Performance

`performance_analyze_insight`

Description: Provides more detailed information on a specific Performance Insight of an insight set that was highlighted in the results of a trace recording.

Parameters:

  • insightName (string) (required): The name of the Insight you want more information on. For example: "DocumentLatency" or "LCPBreakdown"
  • insightSetId (string) (required): The id for the specific insight set. Only use the ids given in the "Available insight sets" list.

`performance_start_trace`

Description: Start a performance trace on the selected webpage. Use to find frontend performance issues, Core Web Vitals (LCP, INP, CLS), and improve page load speed.

Parameters:

  • autoStop (boolean) (optional): Determines if the trace recording should be automatically stopped.
  • filePath (string) (optional): The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).
  • reload (boolean) (optional): Determines if, once tracing has started, the current selected page should be automatically reloaded. Navigate the page to the right URL using the navigate_page tool BEFORE starting the trace if reload or autoStop is set to true.

`performance_stop_trace`

Description: Stop the active performance trace recording on the selected webpage.

Parameters:

  • filePath (string) (optional): The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).

Network

`get_network_request`

Description: Gets a network request by an optional reqid, if omitted returns the currently selected request in the DevTools Network panel.

Parameters:

  • reqid (number) (optional): The reqid of the network request. If omitted returns the currently selected request in the DevTools Network panel.
  • requestFilePath (string) (optional): The absolute or relative path to a .network-request file to save the request body to. If omitted, the body is returned inline.
  • responseFilePath (string) (optional): The absolute or relative path to a .network-response file to save the response body to. If omitted, the body is returned inline.

`list_network_requests`

Description: Lists the most recent requests for the currently selected page since the last navigation.

Parameters:

  • includePreservedRequests (boolean) (optional): Set to true to return the preserved requests over the last 3 navigations.
  • pageIdx (integer) (optional): Page number to return (0-based). When omitted, returns the first page.
  • pageSize (integer) (optional): Maximum number of requests to return. When omitted, returns all requests.
  • resourceTypes (array) (optional): Filter requests to only return requests of the specified resource types. When omitted or empty, returns all requests.

Debugging

`evaluate_script`

Description: Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON, so returned values have to be JSON-serializable.

Parameters:

  • function (string) (required): A JavaScript function declaration to be executed by the tool in the currently selected page.
    Example without arguments: () => document.title or async () => await fetch("example.com").
    Example with arguments: (el) => el.innerText

  • args (array) (optional): An optional list of arguments to pass to the function.

  • dialogAction (string) (optional): Handle dialogs while execution. "accept", "dismiss", or string for response of window.prompt. Defaults to accept.

  • filePath (string) (optional): The absolute or relative path to a file to save the script output to. If omitted, the output is returned inline.

  • waitForStableDom (boolean) (optional): Whether to wait for the DOM to settle. Pass false if the script only reads data. Defaults to true.

`get_console_message`

Description: Gets a console message by its ID. You can get all messages by calling list_console_messages.

Parameters:

  • msgid (number) (required): The msgid of a console message on the page from the listed console messages

`lighthouse_audit`

Description: Get Lighthouse score and reports for accessibility, SEO, best practices, and agentic browsing. This excludes performance. For performance audits, run performance_start_trace

Parameters:

  • device (enum: "desktop", "mobile") (optional): Device to emulate.
  • mode (enum: "navigation", "snapshot") (optional): "navigation" reloads & audits. "snapshot" analyzes current state.
  • outputDirPath (string) (optional): Directory for reports. If omitted, uses temporary files.

`list_console_messages`

Description: List all console messages for the currently selected page since the last navigation.

Parameters:

  • includePreservedMessages (boolean) (optional): Set to true to return the preserved messages over the last 3 navigations.
  • includeStackTraces (boolean) (optional): Set to true to include the stack trace for each message when available. Increases the response size.
  • pageIdx (integer) (optional): Page number to return (0-based). When omitted, returns the first page.
  • pageSize (integer) (optional): Maximum number of messages to return. When omitted, returns all messages.
  • serviceWorkerId (string) (optional): Filter messages to only return messages of the specified service worker.
  • types (array) (optional): Filter messages to only return messages of the specified resource types. When omitted or empty, returns all messages.

`take_screenshot`

Description: Take a screenshot of the page or element.

Parameters:

  • filePath (string) (optional): The absolute path, or a path relative to the current working directory, to save the screenshot to instead of attaching it to the response.
  • format (enum: "png", "jpeg", "webp") (optional): Type of format to save the screenshot as. Default is "png"
  • fullPage (boolean) (optional): If set to true takes a screenshot of the full page instead of the currently visible viewport. Incompatible with uid.
  • quality (number) (optional): Compression quality for JPEG and WebP formats (0-100). Higher values mean better quality but larger file sizes. Ignored for PNG format.
  • uid (string) (optional): The uid of an element on the page from the page content snapshot. If omitted, takes a page screenshot.

`take_snapshot`

Description: Take a text snapshot of the currently selected page based on the a11y tree. The snapshot lists page elements along with a unique
identifier (uid). Always use the latest snapshot. Prefer taking a snapshot over taking a screenshot. The snapshot indicates the element selected
in the DevTools Elements panel (if any).

Parameters:

  • filePath (string) (optional): The absolute path, or a path relative to the current working directory, to save the snapshot to instead of attaching it to the response.
  • verbose (boolean) (optional): Whether to include all possible information available in the full a11y tree. Default is false.

`screencast_start`

Description: Starts recording a screencast (video) of the selected page in specified format. (requires flag: --experimentalScreencast=true)

Parameters:

  • filePath (string) (optional): Output file path (.webm,.mp4 are supported). Uses mkdtemp to generate a unique path if not provided.

`screencast_stop`

Description: Stops the active screencast recording on the selected page. (requires flag: --experimentalScreencast=true)

Parameters: None

Memory

`take_heapsnapshot`

Description: Capture a heap snapshot of the currently selected page. Use to analyze the memory distribution of JavaScript objects and debug memory leaks.

Parameters:

  • filePath (string) (required): A path to a .heapsnapshot file to save the heapsnapshot to.

`close_heapsnapshot`

Description: Closes a previously loaded memory heapsnapshot, freeing its memory. (requires flag: --memoryDebugging=true)

Parameters:

  • filePath (string) (required): A path to the .heapsnapshot file to close.

`compare_heapsnapshots`

Description: Loads two memory heapsnapshots and returns the comparison. If classIndex is provided, returns detailed diff for that class, otherwise returns summary diff. (requires flag: --memoryDebugging=true)

Parameters:

  • baseFilePath (string) (required): A path to the base .heapsnapshot file (earlier snapshot).
  • currentFilePath (string) (required): A path to the current .heapsnapshot file (later snapshot).
  • classIndex (number) (optional): Optional 0-based index of the class in the summary list to filter results, showing individual objects.

`get_heapsnapshot_class_nodes`

Description: Loads a memory heapsnapshot and returns instances of a specific class with their IDs. (requires flag: --memoryDebugging=true)

Parameters:

  • filePath (string) (required): A path to a .heapsnapshot file to read.
  • id (number) (required): The ID for the class, obtained from details.
  • filterName (enum: "objectsRetainedByDetachedDomNodes", "objectsRetainedByConsole", "objectsRetainedByEventHandlers", "objectsRetainedByContexts", "sharedNativeContext", "noNativeContext", "attributedToSpecificNativeContext") (optional): An optional filter to apply to the nodes.
  • objectId (number) (optional): The object ID (nodeId) of the specific native context to filter by when filterName is attributedToSpecificNativeContext.
  • pageIdx (number) (optional): The page index for pagination.
  • pageSize (number) (optional): The page size for pagination.

`get_heapsnapshot_details`

Description: Loads a memory heapsnapshot and returns all available information including statistics, static data, and aggregated node information. Supports pagination for aggregates. (requires flag: --memoryDebugging=true)

Parameters:

  • filePath (string) (required): A path to a .heapsnapshot file to read.
  • filterName (enum: "objectsRetainedByDetachedDomNodes", "objectsRetainedByConsole", "objectsRetainedByEventHandlers", "objectsRetainedByContexts", "sharedNativeContext", "noNativeContext", "attributedToSpecificNativeContext") (optional): An optional filter to apply to the aggregates.
  • objectId (number) (optional): The object ID (nodeId) of the specific native context to filter by when filterName is attributedToSpecificNativeContext.
  • pageIdx (number) (optional): The page index for pagination of aggregates.
  • pageSize (number) (optional): The page size for pagination of aggregates.

`get_heapsnapshot_dominators`

Description: Loads a memory heapsnapshot and returns the dominator chain for a specific node ID. This helps to identify which objects are keeping the target node alive. (requires flag: --memoryDebugging=true)

Parameters:

  • filePath (string) (required): A path to a .heapsnapshot file to read.
  • nodeId (number) (required): The node ID to get the dominator chain for.

`get_heapsnapshot_duplicate_strings`

Description: Loads a memory heapsnapshot and returns duplicate strings grouped by their value. (requires flag: --memoryDebugging=true)

Parameters:

  • filePath (string) (required): A path to a .heapsnapshot file to read.
  • pageIdx (number) (optional): The page index for pagination.
  • pageSize (number) (optional): The page size for pagination.

`get_heapsnapshot_edges`

Description: Loads a memory heapsnapshot and returns outgoing edges (references) for a specific node ID. (requires flag: --memoryDebugging=true)

Parameters:

  • filePath (string) (required): A path to a .heapsnapshot file to read.
  • nodeId (number) (required): The node ID to get outgoing edges for.
  • excludePrimitives (boolean) (optional): Whether to exclude primitive target nodes. Default is true.
  • pageIdx (number) (optional): The page index for pagination.
  • pageSize (number) (optional): The page size for pagination.
  • retainedSize (string) (optional): Inclusive retained size range (e.g. "1MB-2MB", "-1MB", or "1MB-") for target nodes. A single value is treated as a minimum. Currently, only the lower bound is applied.
  • sortBy (enum: "retainedSize", "selfSize", "name") (optional): Sort order for edges. Default is retainedSize.

`get_heapsnapshot_object_details`

Description: Loads a memory heapsnapshot and returns detailed information about a specific object by its node ID, including size, type, distance, and DOM detachedness. (requires flag: --memoryDebugging=true)

Parameters:

  • filePath (string) (required): A path to a .heapsnapshot file to read.
  • nodeId (number) (required): The node ID to get object details for.

`get_heapsnapshot_retainers`

Description: Loads a memory heapsnapshot and returns retainers for a specific node ID. (requires flag: --memoryDebugging=true)

Parameters:

  • filePath (string) (required): A path to a .heapsnapshot file to read.
  • nodeId (number) (required): The node ID to get retainers for.
  • pageIdx (number) (optional): The page index for pagination.
  • pageSize (number) (optional): The page size for pagination.

`get_heapsnapshot_retaining_paths`

Description: Loads a memory heapsnapshot and returns retaining paths for a specific node ID. This helps to understand why a node is not being garbage collected. (requires flag: --memoryDebugging=true)

Parameters:

  • filePath (string) (required): A path to a .heapsnapshot file to read.
  • nodeId (number) (required): The node ID to get retaining paths for.
  • maxDepth (number) (optional): The maximum depth to search for retaining paths.
  • maxNodes (number) (optional): The maximum number of nodes to return.
  • maxSiblings (number) (optional): The maximum number of siblings to return.

`get_heapsnapshot_summary`

Description: Loads a memory heapsnapshot and returns snapshot summary stats, including native contexts and their sizes, and retained by context summary. (requires flag: --memoryDebugging=true)

Parameters:

  • filePath (string) (required): A path to a .heapsnapshot file to read.

`query_heapsnapshot_objects`

Description: Loads a memory heapsnapshot and queries objects matching specific filters (className, propertyName, nodeType, retainedSize, selfSize, isDetached, sortBy). (requires flag: --memoryDebugging=true)

Parameters:

  • filePath (string) (required): A path to a .heapsnapshot file to read.
  • className (string) (optional): Optional regex or text matching object class name.
  • isDetached (boolean) (optional): Whether to filter for detached DOM nodes.
  • nodeType (string) (optional): Optional V8 node type filter (e.g. object, closure, string, array, code).
  • pageIdx (number) (optional): The page index for pagination.
  • pageSize (number) (optional): The page size for pagination.
  • propertyName (string) (optional): Optional property name filter for outgoing reference edges.
  • retainedSize (string) (optional): Inclusive retained size range (e.g. "1MB-2MB", "-1MB", or "1MB-"). A single value is treated as a minimum.
  • selfSize (string) (optional): Inclusive self size range (e.g. "1MB-2MB", "-1MB", or "1MB-"). A single value is treated as a minimum.
  • sortBy (enum: "retainedSize", "selfSize", "id") (optional): Sort order for results. Default is retainedSize.

Extensions

NOTE: The Extensions category is not active by default. Use the '--categoryExtensions' flag.

`install_extension`

Description: Installs a Chrome extension from the given path. (requires flag: --categoryExtensions=true)

Parameters:

  • path (string) (required): Absolute path to the unpacked extension folder.

`list_extensions`

Description: Lists all the Chrome extensions installed in the browser. This includes their name, ID, version, and enabled status. (requires flag: --categoryExtensions=true)

Parameters: None

`reload_extension`

Description: Reloads an unpacked Chrome extension by its ID. (requires flag: --categoryExtensions=true)

Parameters:

  • id (string) (required): ID of the extension to reload.

`trigger_extension_action`

Description: Triggers the default action of an extension by its ID. (requires flag: --categoryExtensions=true)

Parameters:

  • id (string) (required): ID of the extension to trigger the action for.

`uninstall_extension`

Description: Uninstalls a Chrome extension by its ID. (requires flag: --categoryExtensions=true)

Parameters:

  • id (string) (required): ID of the extension to uninstall.

Third-party

NOTE: The Third-party category is not active by default. Use the '--categoryExperimentalThirdParty' flag.

`execute_3p_developer_tool`

Description: Executes a tool exposed by the page. (requires flag: --categoryExperimentalThirdParty=true)

Parameters:

  • toolName (string) (required): The name of the tool to execute
  • params (string) (optional): The JSON-stringified parameters to pass to the tool

`list_3p_developer_tools`

Description: Lists all third-party developer tools the page exposes for providing runtime information.
Third-party developer tools can be called via the 'execute_3p_developer_tool()' MCP tool.
Alternatively, third-party developer tools can be executed by calling 'evaluate_script' and adding the
following command to the script:
window.__dtmcp.executeTool(toolName, params)
This might be helpful when the third-party developer tools return non-serializable values or when composing
third-party developer tools with additional functionality. (requires flag: --categoryExperimentalThirdParty=true)

Parameters: None

WebMCP

NOTE: The WebMCP category is not active by default. Use the '--categoryExperimentalWebmcp' flag.

`execute_webmcp_tool`

Description: Executes a WebMCP tool exposed by the page. (requires flag: --categoryExperimentalWebmcp=true)

Parameters:

  • toolName (string) (required): The name of the WebMCP tool to execute
  • input (string) (optional): The JSON-stringified parameters to pass to the WebMCP tool

`list_webmcp_tools`

Description: Lists all WebMCP tools the page exposes. (requires flag: --categoryExperimentalWebmcp=true)

Parameters: None

Progressive Web Apps

NOTE: The Progressive Web Apps category is not active by default. Use the '--categoryPwa' flag.

`get_os_app_state`

Description: Returns the OS integration state (badge count and registered file handlers) for an installed web app, identified by its manifest ID. (requires flag: --categoryPwa=true)

Parameters:

`install_pwa`

Description: Installs a Progressive Web App (PWA) identified by its manifest ID. This installs through the PWA CDP domain without a user gesture or install dialog. DevTools installs default to browser display mode. (requires flag: --categoryPwa=true)

Parameters:

  • installUrlOrBundleUrl (string) (required): The location of the app or bundle. For a normal site this is the page URL; for an Isolated Web App it can be a file:// or http(s):// signed web bundle.
  • manifestId (string) (required): The manifest ID of the web app: the resolved id member of its manifest. If id is omitted, it defaults to the resolved start_url (e.g. "https://example.com/"). See https://w3c.github.io/manifest/#id-member.
  • displayMode (enum: "standalone", "browser") (optional): Optional user display mode preference applied after install. "standalone" opens the app in its own window; "browser" opens it as a tab. Installs via the PWA CDP domain default to "browser" because they do not simulate the install dialog, so pass "standalone" to get an app-window experience.

`launch_pwa`

Description: Launches an installed Progressive Web App using its saved display mode. Optionally opens a specific URL within the same app instead of the default start URL. (requires flag: --categoryPwa=true)

Parameters:

  • manifestId (string) (required): The manifest ID of the web app: the resolved id member of its manifest. If id is omitted, it defaults to the resolved start_url (e.g. "https://example.com/"). See https://w3c.github.io/manifest/#id-member.
  • url (string) (optional): Optional URL within the app to open instead of the default start URL.

`uninstall_pwa`

Description: Uninstalls a Progressive Web App identified by its manifest ID and closes any open app windows. (requires flag: --categoryPwa=true)

Parameters:

File: docs/troubleshooting.md

Troubleshooting

General tips

  • Run npx chrome-devtools-mcp@latest --help to test if the MCP server runs on your machine.
  • Make sure that your MCP client uses the same npm and node version as your terminal.
  • When configuring your MCP client, try using the --yes argument to npx to
    auto-accept installation prompt.
  • Find a specific error in the output of the chrome-devtools-mcp server.
    Usually, if your client is an IDE, logs would be in the Output pane.
  • Search the GitHub repository issues and discussions for help or existing similar problems.

Debugging

Start the MCP server with debugging enabled and a log file:

  • DEBUG=* npx chrome-devtools-mcp@latest --log-file=/path/to/chrome-devtools-mcp.log

Using .mcp.json to debug while using a client:

json
{
  "mcpServers": {
    "chrome-devtools": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--log-file",
        "/path/to/chrome-devtools-mcp.log"
      ],
      "env": {
        "DEBUG": "*"
      }
    }
  }
}

Specific problems

`Error [ERR_MODULE_NOT_FOUND]: Cannot find module ...`

This usually indicates either a non-supported Node version is in use or that the
npm/npx cache is corrupted. Try clearing the cache, uninstalling
chrome-devtools-mcp and installing it again. Clear the cache by running:

sh
rm -rf ~/.npm/_npx # NOTE: this might remove other installed npx executables.
npm cache clean --force

`Target closed` error

This indicates that the browser could not be started. Make sure that no Chrome
instances are running or close them. Make sure you have the latest stable Chrome
installed and that your system is able to run Chrome.

Chrome crashes on macOS when using Web Bluetooth

On macOS, Chrome launched by an MCP client application (such as Claude Desktop) may crash when a Web Bluetooth prompt appears. This is caused by a macOS privacy permission violation (TCC).

To resolve this, grant Bluetooth permission to the MCP client application in System Settings > Privacy & Security > Bluetooth. After granting permission, restart the client application and start a new MCP session.

Remote debugging between virtual machine (VM) and host fails

When attempting to connect to Chrome running on a host machine from within a virtual machine (VM), Chrome may reject the connection due to 'Host' header validation. You can bypass this restriction by creating an SSH tunnel from the VM to the host. In the VM, run:

sh
ssh -N -L 127.0.0.1:9222:127.0.0.1:9222 @<host-ip>

Point the MCP connection inside the VM to http://127.0.0.1:9222. This allows DevTools to reach the host browser without triggering the Host validation error.

Operating system sandboxes

Some MCP clients allow sandboxing the MCP server using macOS Seatbelt or Linux
containers. If sandboxes are enabled, chrome-devtools-mcp is not able to start
Chrome that requires permissions to create its own sandboxes. As a workaround,
either disable sandboxing for chrome-devtools-mcp in your MCP client or use
--browser-url to connect to a Chrome instance that you start manually outside
of the MCP client sandbox.

WSL

By default, chrome-devtools-mcp in WSL requires Chrome to be installed within the Linux environment. While it normally attempts to launch Chrome on the Windows side, this currently fails due to a known WSL issue. Ensure you are using a Linux distribution compatible with Chrome.

Possible workarounds include:

  • Install Google Chrome in WSL:

    • wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
    • sudo dpkg -i google-chrome-stable_current_amd64.deb

  • Use Mirrored networking:

    1. Configure Mirrored networking for WSL.
    2. Start Chrome on the Windows side with:
      chrome.exe --remote-debugging-port=9222 --user-data-dir=C:\path\to\dir
    3. Start chrome-devtools-mcp with:
      npx chrome-devtools-mcp --browser-url http://127.0.0.1:9222

  • Use PowerShell or Git Bash instead of WSL.

Windows 10: Error during discovery for MCP server 'chrome-devtools': MCP error -32000: Connection closed

  • Solution 1 Call using cmd (For more info https://github.com/modelcontextprotocol/servers/issues/1082#issuecomment-2791786310)

    json
    "mcpServers": {
    "chrome-devtools": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "chrome-devtools-mcp@latest"]
    }
  }

    The Key Change: On Windows, running a Node.js package via npx often requires the cmd /c prefix to be executed correctly from within another process like VSCode's extension host. Therefore, "command": "npx" was replaced with "command": "cmd", and the actual npx command was moved into the "args" array, preceded by "/c". This fix allows Windows to interpret the command correctly and launch the server.

  • Solution 2 Instead of another layer of shell you can write the absolute path to npx:

    Note: The path below is an example. You must adjust it to match the actual location of npx on your machine. Depending on your setup, the file extension might be .cmd, .bat, or .exe rather than .ps1. Also, ensure you use double backslashes (\\) as path delimiters, as required by the JSON format.

    json
    "mcpServers": {
    "chrome-devtools": {
      "command": "C:\\nvm4w\\nodejs\\npx.ps1",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }

Claude Code plugin installation fails with `Failed to clone repository`

When installing chrome-devtools-mcp as a Claude Code plugin (either from the
official marketplace or via /plugin marketplace add), the installation may fail
with a timeout error if your environment cannot reach github.com on port 443
(HTTPS):

text
Failed to download/cache plugin chrome-devtools-mcp: Failed to clone repository:
  Cloning into '...'...
  fatal: unable to access 'https://github.com/ChromeDevTools/chrome-devtools-mcp.git/':
  Failed to connect to github.com port 443

This can happen in environments with restricted outbound HTTPS connectivity,
corporate firewalls, or proxy configurations that block HTTPS git operations.

Workaround 1: Use SSH instead of HTTPS

If you have SSH access to GitHub configured, you can redirect all GitHub HTTPS
URLs to use SSH by running:

sh
git config --global url."[email protected]:".insteadOf "https://github.com/"

Then retry the plugin installation. This tells git to use your SSH key for all
GitHub operations instead of HTTPS.

Workaround 2: Install via CLI instead

If the plugin marketplace approach fails, you can install chrome-devtools-mcp
as an MCP server directly without cloning the repository:

sh
claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest

This bypasses the git clone entirely and uses npm/npx to fetch the package. Note
that this method installs only the MCP server without the bundled skills.

Connection timeouts with `--autoConnect`

If you are using the --autoConnect flag and tools like list_pages, new_page, or navigate_page fail with a timeout (e.g., ProtocolError: Network.enable timed out or The socket connection was closed unexpectedly), this usually means the MCP server cannot handshake with the running Chrome instance correctly. Ensure:

  1. Chrome 144+ is already running.
  2. Remote debugging is enabled in Chrome via chrome://inspect/#remote-debugging.
  3. You have allowed the remote debugging connection prompt in the browser.
  4. There is no other MCP server or tool trying to connect to the same debugging port.

[!IMPORTANT]
In Chrome versions up to 149, connection issues may be caused by frozen or unloaded tabs.
Chrome DevTools MCP forces all tabs to be loaded, so ensure your system has sufficient resources.
It is currently not recommended to use Chrome DevTools MCP with browser instances running hundreds of tabs.
See Issue #1921 for more details.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#browser Browse browser catalog → #chrome Browse chrome catalog → #chrome-devtools Browse chrome-devtools catalog → #debugging Browse debugging catalog → #devtools Browse devtools catalog → #mcp Browse mcp catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →