AI coding agents can write a web page, but most of them can’t see what that page does once it runs in a browser. Chrome DevTools MCP, an open-source server from the Chrome DevTools team, fixes that by letting an agent such as Claude Code, Cursor, Copilot or Gemini CLI open Chrome, read the console, inspect network requests, take screenshots and record performance traces. This guide shows you how to install it, run a first test, connect it to a Chrome window you already have open, and fix the most common setup problems.
As of 14 November 2026 the latest release is version 1.13.0, published on 11 November, and the project was on GitHub’s daily trending list this week.
What Chrome DevTools MCP does
MCP (Model Context Protocol) is a standard way for AI assistants to call outside tools. The chrome-devtools-mcp package is an MCP server: your agent sends it requests like “open this URL” or “list console errors”, and it carries them out in a real Chrome browser using Chrome DevTools and Puppeteer.
The tools are grouped into categories. Input automation (click, fill, type, upload a file), navigation, emulation, performance tracing, network inspection and debugging (console messages, screenshots, page snapshots, Lighthouse audits) are on by default. Extra categories such as network mocks, extensions and progressive web apps are off until you turn them on with a flag. The 1.13.0 release added logpoints and page-scoped network mocks.
The same package also includes a chrome-devtools command-line tool, so you can drive the browser from a terminal without an agent at all.
What you need
- Node.js, an LTS version. As of 14 November 2026 the npm package lists support for Node
^20.19.0 || ^22.12.0 || >=23. - npm (it comes with Node).
- Google Chrome, current stable version or newer. The project officially supports only Google Chrome and Chrome for Testing; other Chromium browsers may work but aren’t guaranteed.
- An MCP-capable agent or editor, for example Claude Code, Cursor, VS Code with Copilot, Gemini CLI or Codex.
Check your Node version first:
node --version
Step 1: Check that the server runs
Before touching your agent’s settings, confirm the package starts on your machine. The official troubleshooting guide recommends this test:
npx chrome-devtools-mcp@latest --help
You should see a list of options such as --headless, --isolated and --browser-url. If you get an error here, fix it before going further (see the errors section below).
Step 2: Add it to your agent
Most MCP clients accept the same JSON block. This is the standard configuration from the project’s README:
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": ["-y", "chrome-devtools-mcp@latest"]
}
}
}
Using @latest means your client picks up new versions automatically.
Several tools also have a one-line install. These come from the project’s client configuration guide.
Claude Code:
claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest
Gemini CLI:
gemini mcp add chrome-devtools npx chrome-devtools-mcp@latest
OpenAI Codex:
codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
VS Code (macOS and Linux):
code --add-mcp '{"name":"io.github.ChromeDevTools/chrome-devtools-mcp","command":"npx","args":["-y","chrome-devtools-mcp"],"env":{}}'
In Cursor, the guide says to go to Cursor Settings, then MCP, then New MCP Server, and paste the standard config. Menu names can change between releases, so if you can’t find that path, check Cursor’s own MCP docs.
Optional: install it as a plugin with skills
The project also ships “skills”, short instruction files that teach your agent how to use the tools well. In Claude Code you can install the server and skills together by running /plugin marketplace add ChromeDevTools/chrome-devtools-mcp and then /plugin install chrome-devtools-mcp@chrome-devtools-plugins, then restarting Claude Code. If skills are new to you, our guide on how to install and use agent skills in Claude Code explains how they work.
Step 3: Run your first prompt
Restart your agent so it loads the new server, then type the test prompt the project suggests:
Check the performance of https://developers.chrome.com
Expected result: a Chrome window opens, the page loads, and your agent reports back on a performance trace. The browser only starts when the agent first uses a tool that needs it, so connecting the server on its own won’t open Chrome.
Once that works, try prompts that match your own work:
Open http://localhost:3000, list any console errors, and tell me which network requests failed.
Take a screenshot of http://localhost:3000 at a mobile viewport and check the page for accessibility problems.
By default the server launches Chrome with its own profile stored in $HOME/.cache/chrome-devtools-mcp/chrome-profile on macOS and Linux. That profile is kept between runs, so logins you make there persist.
Step 4: Change how Chrome starts (optional)
You control behaviour by adding flags to the args array. This example runs Chrome without a window, uses a temporary profile that is deleted afterwards, and opts out of Google’s usage statistics, which are collected by default:
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": [
"-y",
"chrome-devtools-mcp@latest",
"--headless=true",
"--isolated=true",
"--no-usage-statistics"
]
}
}
}
Two other privacy settings are worth knowing. Performance tools may send trace URLs to Google’s Chrome UX Report (CrUX) API to fetch real-user data; add --no-performance-crux to stop that. If you only need basic browsing, --slim exposes a reduced set of three tools.
Step 5: Connect to a Chrome window you already use (optional)
Sometimes you want the agent to work in your own browser, for example on a site you’re already signed into. As of 14 November 2026 this “auto connect” mode needs Chrome 144 or newer.
- In Chrome, go to
chrome://inspect/#remote-debuggingand follow the dialog to allow incoming debugging connections. - Add
--autoConnectto your config:
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": ["chrome-devtools-mcp@latest", "--autoConnect"]
}
}
}
- Keep Chrome running and send a prompt. Chrome asks for permission; click Allow.
The server connects to your default Chrome profile and can see every open window in it. Close tabs with banking, email or other sensitive data first. The project’s own disclaimer warns that the agent can inspect and modify any data in the browser.
If your agent runs in a sandbox, the alternative is to start Chrome yourself with a debugging port and a separate profile (macOS shown; the docs list Linux and Windows paths too):
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable
Then use "--browser-url=http://127.0.0.1:9222" in args. Any app on your machine can control the browser while that port is open, so don’t browse sensitive sites in that window.
Common errors and fixes
Error [ERR_MODULE_NOT_FOUND]: Cannot find module ...: usually an unsupported Node version or a corrupted npx cache. Update Node, then clear the cache withnpm cache clean --forceand reinstall. The docs also suggestrm -rf ~/.npm/_npx, which removes other cached npx tools as well.Target closed: Chrome couldn’t start. Make sure no other Chrome instances are running (close them if they are) and that the latest stable Chrome is installed.- Agent can’t find the server, but the terminal test works: make sure your editor uses the same Node and npm as your terminal.
- Windows:
MCP error -32000: Connection closed: set"command": "cmd"and put"/c", "npx", "-y", "chrome-devtools-mcp@latest"inargs. - macOS:
--autoConnectfails withEPERM: operation not permitted: grant your terminal or editor access to Google Chrome in System Settings > Privacy & Security > Files & Folders. --autoConnecttimes out: check that Chrome 144+ is already running, remote debugging is enabled atchrome://inspect/#remote-debugging, you accepted the prompt, and nothing else is using the same debugging port.- Chrome won’t start in a container or CI: Chrome doesn’t run as root. Run the server as a non-root user.
- Working inside a VM: Chrome may reject connections from the VM. The docs suggest an SSH tunnel from the VM, for example
ssh -N -L 127.0.0.1:9222:127.0.0.1:9222 user@server. Our SSH keys guide covers the setup if you haven’t used SSH before.
For anything else, run the server with a log file and read the error:
NODE_DEBUG=* npx chrome-devtools-mcp@latest --log-file=/tmp/chrome-devtools-mcp.log
Wrap-up
Chrome DevTools MCP lets your agent check its own front-end work: load the page, read the errors, look at the network tab and measure performance, instead of guessing. Start with the standard config and the test prompt, add --isolated or --headless if you want a clean throwaway browser, and use auto connect only in a profile where you’re comfortable with an AI seeing everything. Keep Chrome itself updated too; our Chrome zero-day explainer explains why that matters.
Sources
Links last checked on 15 November 2026.





Write a response