chrome-devtools-mcp
CLI ToolChromeDevTools/chrome-devtools-mcp
MCP server giving AI coding agents control of Chrome DevTools.
Overview
Chrome DevTools MCP server that enables AI agents to debug, automate, and analyze Chrome browser performance. Integrates with Puppeteer and Chrome DevTools Frontend for reliable automation and performance insights.
README Preview
# Chrome DevTools for Agents\n\n[](https://npmjs.org/package/chrome-devtools-mcp)\n\nChrome DevTools for Agents (`chrome-devtools-mcp`) lets your coding agent (such as Gemini, Claude, Cursor or Copilot)\ncontrol and inspect a live Chrome browser. It acts as a Model-Context-Protocol\n(MCP) server, giving your AI coding assistant access to the full power of\nChrome DevTools for reliable automation, in-depth debugging, and performance analysis.\nA [CLI](docs/cli.md) is also provided for use without MCP.\n\n## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md) | [Design Principles](./docs/design-principles.md)\n\n## Key features\n\n- **Get performance insights**: Uses [Chrome\n DevTools](https://github.com/ChromeDevTools/devtools-frontend) to record\n traces and extract actionable performance insights.\n- **Advanced browser debugging**: Analyze network requests, take screenshots and\n check browser console messages (with source-mapped stack traces).\n- **Reliable automation**. Uses\n [puppeteer](https://github.com/puppeteer/puppeteer) to automate actions in\n Chrome and automatically wait for action results.\n\n## Disclaimers\n\n`chrome-devtools-mcp` exposes content of the browser instance to the MCP clients\nallowing them to inspect, debug, and modify any data in the browser or DevTools.\nAvoid sharing sensitive or personal information that you don't want to share with\nMCP clients.\n\n`chrome-devtools-mcp` officially supports Google Chrome and [Chrome for Testing](https://developer.chrome.com/blog/chrome-for-testing/) only.\nOther Chromium-based browsers may work, but this is not guaranteed, and you may encounter unexpected behavior. Use at your own discretion.\nWe are committed to providing fixes and support for the latest version of [Extended Stable Chrome](https://chromiumdash.appspot.com/schedule).\n\nPerformance tools may send trace URLs to the Google CrU
FAQ (5)
TroubleshootingHow to fix 'Navigation timeout' error when using emulate() to set mobile viewport and network throttle simultaneously in chrome-devtools-mcp?
This is a known issue in chrome-devtools-mcp v1.0.1. The network throttle is applied before the navigation timeout multiplier is updated, causing a default 10s timeout when the viewport change triggers a page reload under slow network conditions like Slow 3G. Workaround: split the emulate call into two separate calls. For example, first call emulate with only networkConditions, then a second call with viewport (or vice versa). This avoids the reload occurring without the extended timeout. A permanent fix has been proposed in PR #2134.
TroubleshootingHow to fix chrome-devtools-mcp Claude Code plugin failing to start with npm EOVERRIDE error (CONNECTION_CLOSED)?
The plugin launches the server with npx chrome-devtools-mcp@<version>, and npx resolves against the package.json in your current working directory. If your project has an overrides entry that conflicts with a direct dependency (common after Dependabot/Renovate bumps a dependency without updating the pinned security override, e.g. "dependencies": {"dompurify": "^3.4.16"} vs "overrides": {"dompurify": "^3.4.14"}), npx exits with npm error code EOVERRIDE before the server starts, and Claude Code only shows Connection failed (CONNECTION_CLOSED).
Workarounds:
1. Fix your project's package.json: align the overrides version with the direct dependency (update the override to the same range as the dependency), then run npm install.
2. Start Claude Code from a directory whose package.json has no conflicting overrides.
3. Verify the server itself works by bypassing the cwd's package.json:
npx -y --prefix "$HOME" chrome-devtools-mcp@1.11.0 --version
or sh -c 'cd ~ && npx -y chrome-devtools-mcp@1.11.0 --version'
Plugin-level fix: in .claude-plugin/plugin.json, add a prefix to the inline mcpServers args so npx ignores the project's package.json: "args": ["--prefix", "${CLAUDE_PLUGIN_DATA}", "chrome-devtools-mcp@<version>"]. Note Claude Code expands ${CLAUDE_PLUGIN_DATA} and ${HOME}, but NOT ${PLUGIN_DATA} (which appears in the shipped mcp.json that Claude Code ignores).
TroubleshootingWhy do heap snapshot tools show old data after take_heapsnapshot overwrites the same .heapsnapshot file?
The heap snapshot is cached by file path after it is first loaded. Overwriting the same path with take_heapsnapshot does not invalidate the cached snapshot, so get_heapsnapshot_details, query_heapsnapshot_objects, and similar tools continue analyzing the old capture. To force a reload, call close_heapsnapshot for that path before analyzing it again: {"name":"close_heapsnapshot","arguments":{"filePath":"/path/to/same.heapsnapshot"}} followed by get_heapsnapshot_details or query_heapsnapshot_objects. Alternatively, use a unique filePath for every capture, such as snapshot-<timestamp>.heapsnapshot, to avoid the cache entirely.
TroubleshootingHow do I restrict Chrome DevTools MCP CLI file access to the temp directory when --allowUnrestrictedPaths=false doesn't work?
This is a bug in chrome-devtools-mcp 1.10.1 and main commit b2f522c: an explicit --allowUnrestrictedPaths=false is ignored in CLI mode, and in 1.10.1 the flag is not forwarded to the daemon. As a workaround, use --workspace to limit file tools to the OS temp directory:
chrome-devtools stop
chrome-devtools start --workspace="$(node -p "require('os').tmpdir()")" --no-usage-statistics --no-performance-cruxAfter restarting, writes outside that directory should fail with an Access denied: path ... is not within any of the configured workspace roots error. Verify the running daemon with chrome-devtools status. Alternatively, upgrade to a release containing the fix that honors explicit --allowUnrestrictedPaths=false; --workspace remains the recommended replacement for the deprecated flag.
TroubleshootingHow to bypass the 'Allow remote debugging' permission dialog when using Chrome DevTools MCP?
Use a dedicated Chrome profile with remote debugging enabled. Launch Chrome with: --remote-debugging-port=9222 --user-data-dir=/path/to/profile. Then connect your MCP server to http://127.0.0.1:9222. This avoids the permission dialog because the dedicated profile is pre-authorized for debugging. Recommended for development and testing. The feature to persist permission approval was not implemented due to security concerns.