Configuration

Matthias Rohmer

José Luis Zapata

You can configure Chrome DevTools for agents to customize how it interacts with the browser, which tools are enabled, and how it handles data.

Configure the server by passing command-line flags in the args array of your Model Context Protocol (MCP) client configuration file. This is typically the config.json file.

For example, to run Chrome in headless mode and use the Canary channel, use the following configuration:

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

Common configuration scenarios

The following scenarios describe common ways to configure Chrome DevTools for agents.

Run in headless mode

To perform background tasks without a visible browser window, run Chrome in headless (no UI) mode. Add the --headless flag to your server arguments.

Connect to an existing browser session

By default, DevTools for agents starts a new Chrome instance. However, you can connect your agent to an existing browser session. This is useful if your agent needs to investigate an issue in a session you've already started (for example, if you are already signed in).

You can connect to an existing session in two ways:

Automatic connection (Chrome 144+)

If you use the --autoConnect flag, the MCP server automatically connects to an active Chrome instance.

1. In your running Chrome browser, navigate to chrome://inspect/#remote-debugging and enable Remote Debugging.
2. Add --autoConnect to your MCP configuration: json "args": ["chrome-devtools-mcp@latest", "--autoConnect"]
3. When the agent attempts to connect, Chrome shows a dialog asking for permission. Click Allow.

Manual connection

If you cannot use --autoConnect (for example, in a sandboxed environment), you can manually start Chrome with a debugging port and connect using --browser-url.

1. Start Chrome from the terminal with remote debugging enabled and a custom user data directory.
   • macOS: shell /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable
   • Windows: shell start chrome --remote-debugging-port=9222 --user-data-dir=%TEMP%\chrome-profile-stable
   • Linux: shell google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable
2. Configure your agent to connect to this port: json "args": ["chrome-devtools-mcp@latest", "--browser-url=http://127.0.0.1:9222"]

Allow file access outside the temporary directory

Tools that read or write files (for example, saving screenshots, traces, or loading extensions) can only access paths within the configured workspace roots. The server uses the roots that your MCP client provides through the MCP roots capability, plus any directories that you pass with --filesystemRoot (alias --workspace). If your client doesn't provide roots and you don't set --filesystemRoot, file access is limited to the OS temporary directory. Requests for other paths fail with an Access denied: ... is not within any of the configured workspace roots error.

To allow access to a project directory, add --filesystemRoot to your server arguments. You can repeat the flag to allow multiple directories:

"args": ["chrome-devtools-mcp@latest", "--filesystemRoot=/path/to/project"]

Configuration options reference

The following sections list the available configuration flags. For the latest options and updates, see the Chrome DevTools MCP GitHub repository.

Connection options

Use these options to configure how the server connects to Chrome.

Browser launch options

These options apply when the MCP server starts Chrome.

Security and privacy options

Use these options to manage security settings and data privacy.

Feature categories

You can enable or disable groups of tools using these flags.

Screenshot options

Use these options to customize how the agent captures screenshots.

Experimental options

Use these options to enable experimental features that are under development.

Other options

Use these options to configure logging, page routing, and source maps, or to enable a simplified set of tools.

Environment variables

You can also use the following environment variables to configure the server:

• CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: If set, disables usage statistics collection (equivalent to --no-usage-statistics).
• CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS: If set, disables periodic checks for updates.
• CI: If set, disables usage statistics collection.
• NODE_DEBUG: Set to * to enable verbose debug logging (works in conjunction with --logFile).