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.
- In your running Chrome browser, navigate to
chrome://inspect/#remote-debuggingand enable Remote Debugging. - Add
--autoConnectto your MCP configuration:json "args": ["chrome-devtools-mcp@latest", "--autoConnect"] - 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.
- 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
- macOS:
- Configure your agent to connect to this port:
json "args": ["chrome-devtools-mcp@latest", "--browser-url=http://127.0.0.1:9222"]
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.
| Flag | Type | Default | Description |
|---|---|---|---|
--autoConnect or --auto-connect |
boolean | false |
Automatically connects to a locally running Chrome (144+) instance. Requires remote debugging to be enabled using chrome://inspect/#remote-debugging. |
--browserUrl or --browser-url-u |
string | false |
Connect to a running, debuggable Chrome instance (for example, http://127.0.0.1:9222). |
--wsEndpoint or --ws-endpoint-w |
string | false |
WebSocket endpoint to connect to a running Chrome instance (for example, ws://127.0.0.1:9222/devtools/browser/<id>). Alternative to --browserUrl. |
--wsHeaders or --ws-headers |
string | false |
Custom headers for WebSocket connection in JSON format (for example, '{"Authorization":"Bearer token"}'). Only works with --wsEndpoint. |
Browser launch options
These options apply when the MCP server starts Chrome.
| Flag | Type | Default | Description |
|---|---|---|---|
--headless |
boolean | false |
Runs Chrome in headless (no UI) mode. |
--channel |
string | stable |
Specifies the Chrome channel to use. Choices: canary, dev, beta, and stable. |
--executablePath or --executable-path-e |
string | false |
Path to a custom Chrome executable. |
--userDataDir or --user-data-dir |
string | See description | Path to the user data directory. Default is $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE. |
--isolated |
boolean | false |
Creates a temporary user data directory that is automatically cleaned up when the browser closes. |
--viewport |
string | false |
Initial viewport size (for example, 1280x720). In headless mode, max size is 3840x2160. |
--proxyServer or --proxy-server |
string | false |
Proxy server configuration passed to Chrome. |
--chromeArg or --chrome-arg |
array | false |
Additional arguments to pass to Chrome. |
--ignoreDefaultChromeArg or --ignore-default-chrome-arg |
array | false |
Explicitly disable default arguments for Chrome. |
Security and privacy options
Use these options to manage security settings and data privacy.
| Flag | Type | Default | Description |
|---|---|---|---|
--acceptInsecureCerts or --accept-insecure-certs |
boolean | false |
Ignores errors related to self-signed and expired certificates. Use with caution. |
--blockedUrlPattern or --blocked-url-pattern |
array | false |
Restricts network access by blocking specified URL patterns (uses URLPattern). Blocks navigations and subresources. |
--allowedUrlPattern or --allowed-url-pattern |
array | false |
Restricts network access by allowing only specified URL patterns. Requires Chrome 149+. |
--redactNetworkHeaders or --redact-network-headers |
boolean | false |
Redacts sensitive network headers before returning them to the client. |
--usageStatistics or --usage-statistics |
boolean | true |
Enables collection of usage statistics to improve the tool. Can also be disabled using the CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS or CI environment variables. |
--performanceCrux or --performance-crux |
boolean | true |
Sends URLs from performance traces to the Google CrUX API to fetch real-user experience data. |
Feature categories
You can enable or disable groups of tools using these flags.
| Flag | Type | Default | Description |
|---|---|---|---|
--categoryEmulation or --category-emulation |
boolean | true |
Enables tools related to emulation. |
--categoryNetwork or --category-network |
boolean | true |
Enables tools related to network. |
--categoryPerformance or --category-performance |
boolean | true |
Enables tools related to performance. |
--categoryExtensions or --category-extensions |
boolean | false |
Enables tools related to extensions. Only supported with pipe connection. |
--categoryExperimentalThirdParty or --category-experimental-third-party |
boolean | false |
Enables third-party developer tools exposed by the inspected page. |
--categoryExperimentalWebmcp or --category-experimental-webmcp |
boolean | false |
Enables debugging WebMCP tools. Requires Chrome 149+ with WebMCP features enabled. |
--memoryDebugging or --memory-debugging |
boolean | false |
Enables memory debugging tools. |
Screenshot options
Use these options to customize how the agent captures screenshots.
| Flag | Type | Default | Description |
|---|---|---|---|
--screenshotFormat or --screenshot-format |
string | false |
Overrides the default output format (png). Choices: jpeg, png, and webp. The jpeg and webp formats are smaller, which helps reduce context size in AI conversations. |
--screenshotQuality or --screenshot-quality |
number | false |
Overrides compression quality (0-100) for jpeg and webp. |
--screenshotMaxWidth or --screenshot-max-width |
number | false |
Maximum width in pixels. Larger screenshots are downscaled. |
--screenshotMaxHeight or --screenshot-max-height |
number | false |
Maximum height in pixels. Larger screenshots are downscaled. |
Experimental options
Use these options to enable experimental features that are under development.
| Flag | Type | Default | Description |
|---|---|---|---|
--experimentalPageIdRouting or --experimental-page-id-routing |
boolean | false |
Exposes pageId on page-scoped tools to route requests in concurrent agent sessions. |
--experimentalDevtools or --experimental-devtools |
boolean | false |
Enables automation over DevTools targets. |
--experimentalVision or --experimental-vision |
boolean | false |
Enables coordinate-based tools (for example, click_at). Usually requires a computer-use model that can produce accurate coordinates by looking at screenshots. |
--experimentalStructuredContent or --experimental-structured-content |
boolean | false |
Outputs structured formatted content. |
--experimentalIncludeAllPages or --experimental-include-all-pages |
boolean | false |
Includes all kinds of pages (for example, webviews and background pages). |
--experimentalScreencast or --experimental-screencast |
boolean | false |
Exposes screencast tools (requires ffmpeg in PATH). |
--experimentalFfmpegPath or --experimental-ffmpeg-path |
string | false |
Path to ffmpeg executable. |
Other options
Use these options to configure logging or to enable a simplified set of tools.
| Flag | Type | Default | Description |
|---|---|---|---|
--slim |
boolean | false |
Exposes a slim set of three tools (navigation, script execution, and screenshots). Useful for basic browser tasks. |
--logFile or --log-file |
string | false |
Path to a file to write debug logs to. |
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.DEBUG: Set to*to enable verbose debug logging (works in conjunction with--logFile).