Chrome DevTools MCP lets you hand a coding agent the real DevTools on a Linux box. Your agent gets performance traces, console messages with source-mapped stacks and every network request, plus logpoints and page-scoped network mocks since the November release. You need it when an agent has to explain why a page is slow or broken, which a click-and-screenshot tool cannot do.
This guide sets the server up headless as a normal user and registers it with Claude Code. Then it fixes the three errors that stop Chrome on a server, debugs a deliberately broken page, and compares the result with Playwright MCP and agent-browser. We checked chrome-devtools-mcp 1.13.0 with Chrome 157 in November 2026 on Ubuntu 26.04 and 24.04.
What does Chrome DevTools MCP give an agent?
It gives the agent the same panels you would open in DevTools, exposed as MCP tools. The server drives Chrome over the DevTools protocol through Puppeteer, so the agent reads the Performance, Console and Network data you read instead of guessing from a screenshot. The default build exposes 33 tools in seven groups. We counted them on the lab box with a raw MCP client rather than trusting a number from a README.
The release from 11 November added the pieces that make it a debugger rather than a page reader. These are the ones we exercised below, all listed in the chrome-devtools-mcp release notes:
- A
set_logpointstool logs an expression at a source line, resolved through source maps, without editing the code. - A
mock_networktool replaces one URL on one page with a local file, andremove_network_mocktakes it away again. - A mock can point at an upstream URL instead of a file, so a request is answered by another endpoint.
- The server now tells you to use
--headlesswhen it finds no X server, instead of only printing the Puppeteer error.
If all you need is to click through a site or fill a form, a lighter tool will do the job with fewer tokens, and the comparison near the end shows how much lighter. If you need to know why the LCP is three seconds or which line threw, this is the server to install.
What do you need before installing it?
You need three things on the box before the server will start a browser. The npm package declares ^20.19.0 || ^22.12.0 || >=23 as its engine range, and Chrome refuses to run as root, so a root shell on a fresh VPS is the wrong place to start. Check each of these before you install anything else:
- Node.js reports 20.19 or a later 20.x, 22.12 or a later 22.x, or 23 and newer.
- Google Chrome stable is installed from Google’s repository.
- You are logged in as a normal user with sudo rights, not as root.
Ubuntu 26.04 ships a Node.js that fits, so the distro packages are enough there. Install them and print the versions:
sudo apt-get update
sudo apt-get install -y nodejs npm curl gpg
node --version; npm --version
Our 26.04 VM reported Node 22 with npm 9, which sits inside the supported range:
v22.22.1
9.2.0
Ubuntu 24.04 is different, because its archive still carries Node 18. The install does not fail outright. Instead npm prints an EBADENGINE warning and the server exits on its first start with a clear message, which is what we got on the 24.04 VM before fixing it:
npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE package: '[email protected]',
npm WARN EBADENGINE required: { node: '^20.19.0 || ^22.12.0 || >=23' },
npm WARN EBADENGINE current: { node: 'v18.19.1', npm: '9.2.0' }
npm WARN EBADENGINE }
ERROR: `chrome-devtools-mcp` does not support Node v18.19.1. Please upgrade to Node 20.19.0 LTS or a newer LTS.
On 24.04 we removed the distro Node and added the NodeSource repository for the current LTS line. We purged the distro packages first so only one Node and one npm remain on the PATH. On a fresh 24.04 box you can skip that and install only curl gpg in the first block, then go straight to NodeSource.
sudo apt-get purge -y nodejs npm
sudo apt-get autoremove -y
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_26.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list
sudo apt-get update
sudo apt-get install -y nodejs
node --version; npm --version
The NodeSource package bundles its own npm, so there is no separate npm package to install:
v26.13.1
11.20.0
Chrome comes from Google’s own apt repository on both releases. We used Google’s build rather than Ubuntu’s chromium, which installs as a snap, because the server looks for stable Chrome at its standard path and needs no extra flag to find it. Add the signing key and the repository, then install stable Chrome:
curl -fsSL https://dl.google.com/linux/linux_signing_key.pub | sudo gpg --dearmor -o /usr/share/keyrings/google-chrome.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/google-chrome.gpg] https://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt-get update
sudo apt-get install -y google-chrome-stable
google-chrome --version
Both VMs installed the same build, which is what the server finds at /opt/google/chrome/chrome without any path flag:
Google Chrome 157.0.8103.78
Finally, point the npm global prefix at your home directory so global installs do not need sudo. That matters more than it looks, because a global package installed with sudo tempts you into running the server with sudo too. Running as root is the first error in the troubleshooting section, so you avoid it here by never needing root for npm.
npm config set prefix ~/.npm-global
echo 'export PATH=$HOME/.npm-global/bin:$PATH' >> ~/.bashrc
export PATH=$HOME/.npm-global/bin:$PATH
npm install -g chrome-devtools-mcp@latest
chrome-devtools-mcp --version
The global binary is handy for testing outside any agent, and it should print the release you just pulled:
1.13.0
Claude Code itself is not covered here. If it is not on the box yet, our guide to installing Claude Code on Linux covers the native installer and the npm route.
How do you add Chrome DevTools MCP to Claude Code?
For a headless server, use claude mcp add with the flags in the command below, rather than the plugin. The plugin route installs the bundled skills as well, but its server entry is defined upstream, so the launch flags are the project’s choice. With the CLI you choose the flags yourself, and --scope user makes the server available in every project you open.
claude mcp add chrome-devtools --scope user -e CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS=1 -- npx -y chrome-devtools-mcp@latest --headless --isolated --no-usage-statistics --no-performance-crux
claude mcp list
Claude Code writes the entry to ~/.claude.json and starts the server once for its health check. A ✔ Connected status means Node, npx and the package all resolved. It does not yet prove Chrome can start, because Chrome launches on the first tool call, so you still want the test in the next section.

We got the same Connected line on both Ubuntu releases. To see the stored command, scope and environment later, run claude mcp get chrome-devtools, which also prints the matching claude mcp remove chrome-devtools -s user line.
If you want the skills too, the upstream client guide lists the plugin route. You run /plugin marketplace add ChromeDevTools/chrome-devtools-mcp and then /plugin install chrome-devtools-mcp@chrome-devtools-plugins inside Claude Code, followed by a restart. Remove the CLI entry first so you do not end up with two servers driving two Chromes. We did not run the plugin route in this lab, and the Claude Code plugins guide explains how marketplaces and plugin scopes work. For the general model of how MCP servers attach to Claude Code, see our Claude Code MCP servers setup.
Which flags does a headless Linux server need?
Upstream defaults suit a laptop, not a server. Chrome starts headed, a persistent profile collects state between runs, and two features talk to Google. One is usage statistics, and the other is the CrUX lookup that sends the page URL to fetch real-user field data for traces. The table lists the flags we set and why you would want each one.
| Flag or variable | Default | Why we set it |
|---|---|---|
--headless | off (headed) | No X server on a server, so a headed launch fails. |
--isolated | off (shared profile) | Temporary profile, removed when the browser closes, so no cookies leak between sessions. |
--no-usage-statistics | on | Stops usage reporting to Google. |
--no-performance-crux | on | Keeps traced URLs off the CrUX API; field data shows n/a instead. |
CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS=1 | checks on | Turns off the server’s own update check. npx still resolves @latest on launch, so register the global binary if you want no registry call at all. |
--browser-url | unset | Attach to a Chrome you started yourself, used for the sandbox fix below. |
--slim | off | Three tools only (navigate, evaluate, screenshot) for a tiny context. |
--category-network-mocks | off | Adds the two mock tools. |
The privacy flags cost you nothing for local debugging. The one trade is --no-performance-crux, since a public page loses its real-user numbers in the trace summary; for a staging site or a localhost build, CrUX has no data anyway.
How do you test the server without an agent?
Claude Code on our lab VMs was not signed in to an account, so we drove every tool call below with a 68-line MCP stdio client instead. That turned out to be the better test rig for you as well. It prints each raw reply with its run time and size, and it counts the tools/list schema an agent loads before it does anything. Create a folder for it and open the file:
mkdir -p ~/tools && cd ~/tools
vim mcpc.mjs
Paste the client below. It speaks JSON-RPC over the server’s stdin and stdout, follows nextCursor when a server pages its tool list, and swaps {{page}} in a step for the last page ID it saw.
// usage: node mcpc.mjs <steps.json|-> -- <server cmd> [args...]
// steps: [{"tool": "...", "args": {...}}], "{{page}}" is replaced by the last pageId seen.
import { spawn } from 'node:child_process';
import { readFileSync } from 'node:fs';
const sep = process.argv.indexOf('--');
const stepsArg = process.argv[2];
const [cmd, ...args] = process.argv.slice(sep + 1);
const steps = stepsArg === '-' ? [] : JSON.parse(readFileSync(stepsArg, 'utf8'));
const p = spawn(cmd, args, { stdio: ['pipe', 'pipe', 'pipe'] });
let buf = '', id = 0, stderr = '';
const wait = new Map();
p.stderr.on('data', (d) => { stderr += d; });
p.stdout.on('data', (d) => {
buf += d;
let i;
while ((i = buf.indexOf('\n')) >= 0) {
const line = buf.slice(0, i); buf = buf.slice(i + 1);
if (!line.trim()) continue;
let m; try { m = JSON.parse(line); } catch { continue; }
if (m.id && wait.has(m.id)) { wait.get(m.id)(m); wait.delete(m.id); }
}
});
p.on('exit', (c) => {
if (wait.size) {
console.log(`server exited (code ${c}) with ${wait.size} request(s) pending`);
if (stderr.trim()) console.log('--- server stderr ---\n' + stderr.trim());
process.exit(1);
}
});
const req = (method, params = {}) => {
const n = ++id;
p.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: n, method, params }) + '\n');
return new Promise((r) => wait.set(n, r));
};
const init = await req('initialize', { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'mcpc', version: '1' } });
p.stdin.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n');
console.log(`server: ${init.result?.serverInfo?.name} ${init.result?.serverInfo?.version}`);
const tools = [];
let cursor, pages = 0;
do {
const tl = await req('tools/list', cursor ? { cursor } : {});
tools.push(...(tl.result?.tools || []));
cursor = tl.result?.nextCursor;
pages++;
} while (cursor);
console.log(`tools/list pages: ${pages}`);
const schema = JSON.stringify(tools);
console.log(`tools: ${tools.length}`);
console.log(`tools/list JSON: ${schema.length} chars (~${Math.round(schema.length / 4)} tokens at 4 chars/token)`);
if (process.env.LIST_TOOLS) console.log(tools.map((t) => t.name).join('\n'));
let page = 1;
for (const s of steps) {
const a = JSON.parse(JSON.stringify(s.args || {}).replaceAll('"{{page}}"', String(page)));
const t = performance.now();
const m = await req('tools/call', { name: s.tool, arguments: a });
const ms = Math.round(performance.now() - t);
const text = (m.result?.content || []).filter((c) => c.type === 'text').map((c) => c.text).join('\n');
const pm = /pageId[":\s]+(\d+)/.exec(text) || /^(\d+): .*\[selected\]/m.exec(text);
if (pm) page = Number(pm[1]);
console.log(`\n>>> ${s.tool} ${JSON.stringify(a)} (${ms} ms, ${text.length} chars${m.result?.isError ? ', isError' : ''})`);
console.log(m.error ? JSON.stringify(m.error) : (s.max ? text.slice(0, s.max) : text));
}
p.kill();
process.exit(0);
A steps file is a JSON list of tool calls. The smallest useful one opens a page, which is also the call that launches Chrome, so it is the right first test for your setup.
echo '[{"tool":"new_page","args":{"url":"https://example.com/"}},{"tool":"evaluate_script","args":{"pageId":"{{page}}","function":"() => document.title"}}]' > ex.json
CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS=1 node mcpc.mjs ex.json -- chrome-devtools-mcp --headless --isolated --no-usage-statistics --no-performance-crux
On the 24.04 VM the page opened in just over a second and the script call returned the title. If you see this, Chrome starts fine as your user, and any later failure inside Claude Code is a client configuration problem rather than a browser one.
server: chrome_devtools 1.13.0
tools/list pages: 1
tools: 33
tools/list JSON: 32302 chars (~8076 tokens at 4 chars/token)
>>> new_page {"url":"https://example.com/"} (1156 ms, 75 chars)
## Pages
1: about:blank
2: Example Domain (https://example.com/) [selected]
>>> evaluate_script {"pageId":2,"function":"() => document.title"} (211 ms, 61 chars)
Script ran on page and returned:
```json
"Example Domain"
```
Keep the 32,302 characters of tool schema in mind, because they come back in the comparison. At roughly four characters a token, that is about 8,000 tokens of context your agent spends before its first click, on every session where the server is enabled.
Why won’t Chrome start from the MCP server?
On a server it is nearly always one of three causes. We reproduced each one on Ubuntu 26.04, and the messages differ enough that you can tell them apart at a glance. Check them in this order:
- The MCP server runs as a normal user, not as root.
- The server starts with
--headlesswhen the machine has no display. - The MCP client does not wrap the server in an OS sandbox that Chrome cannot nest its own sandbox inside.
Each cause has its own subsection below, with the exact error text so you can match it against what your client prints.
“chrome-devtools-mcp is running as root and Chrome does not start as root”
Chrome exits immediately when started as root without --no-sandbox, so the server reports Target closed and adds a root-specific hint pointing at crbug 638180. We hit it by running the same client under sudo -H:

Do not fix it by adding --no-sandbox to Chrome, because that leaves an agent browsing arbitrary pages with the renderer sandbox off. Run Claude Code and the server as a normal user instead; in a container, add an unprivileged user to the image and switch to it with USER.
“Missing X server to start the headful browser”
Leave out --headless on a machine with no display and Chrome cannot open a window. The current release appends its own hint under the Puppeteer message, and the hint names all three ways out.

For an agent on a server, --headless is the right answer, and every capture in this guide ran headless. Reach for xvfb-run only when you specifically need a headed window, because it adds a virtual X server you will have to keep running alongside the agent.
“Protocol error (Target.setDiscoverTargets): Target closed” inside a sandboxed client
Some MCP clients run servers inside an OS sandbox, and the upstream troubleshooting notes say Chrome cannot create its own sandbox from in there. We reproduced it by wrapping the server in bubblewrap, a user namespace sandbox. The server ran as a normal user with --headless and still got Target closed. Starting Chrome directly in the same sandbox showed the real cause, a SUID sandbox helper that is not usable from inside the namespace.
The fix that keeps both sandboxes is to start Chrome yourself, outside the client, with a debugging port bound to localhost, and let the server attach to it:
nohup google-chrome --headless --remote-debugging-port=9222 --user-data-dir=$HOME/.cache/chrome-mcp-profile >/tmp/chrome-mcp.log 2>&1 &
curl -s http://127.0.0.1:9222/json/version
The version endpoint answering with a HeadlessChrome user agent means the port is live:
{
"Browser": "Chrome/157.0.8103.78",
"File-Path-Style": "posix",
"Protocol-Version": "1.3",
"User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/157.0.0.0 Safari/537.36",
"V8-Version": "15.7.112.43",
Then swap the launch flags for --browser-url=http://127.0.0.1:9222 in the server command. Run inside the same bubblewrap sandbox that failed a minute earlier, it opened the page on the first try:

Two cautions come with this setup. Anything that can reach port 9222 can drive that browser, so keep it on 127.0.0.1 and never publish it. And --isolated no longer applies, because the profile is whatever you passed to Chrome; give it a dedicated directory like the one above, not your daily profile.
To make Claude Code use the running browser, remove the entry you added earlier and register it again with --browser-url in place of the launch flags. The server then attaches to Chrome instead of starting one, so the sandbox never gets in the way.
claude mcp remove chrome-devtools --scope user
claude mcp add chrome-devtools --scope user -e CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS=1 -- npx -y chrome-devtools-mcp@latest --browser-url=http://127.0.0.1:9222 --no-usage-statistics --no-performance-crux
A Chrome started with nohup does not survive a logout or a reboot. If you depend on this route every day, wrap the same command in a systemd user unit so it comes back on its own.
“this CPU is missing SSE4.2 support, which Bun requires”
This one comes from Claude Code, not the MCP server, and it caught our first VM. The Proxmox clone used the generic kvm64 CPU model, which hides SSE4.2, and the Bun runtime inside Claude Code aborts on it. Switching the VM’s CPU type to host and rebooting fixed it, and grep -c sse4_2 /proc/cpuinfo returning a non-zero count is the quick check.
Can it find why a page loads slowly?
Yes, and it reads the trace the way the DevTools Performance panel does. We built a small shop page and broke it on purpose with a 4000×2250 JPEG hero marked loading="lazy" and a missing /api/prices.json. The cart is TypeScript, bundled and minified by esbuild with a source map. nginx served it on port 8080 with limit_rate 400k on /img/, so the 1.2 MB hero takes about three seconds, roughly what it costs on a slow mobile link. You do not need our page to follow along, because every step file below takes a URL, so point it at the slow page on your own staging site instead.
The trace step reloads the page with the cache disabled and stops on its own once the load settles. Save it as trace.json next to the client:
echo '[{"tool":"new_page","args":{"url":"http://127.0.0.1:8080/"}},{"tool":"performance_start_trace","args":{"pageId":"{{page}}","reload":true,"autoStop":true,"ignoreCache":true}}]' > trace.json
CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS=1 node mcpc.mjs trace.json -- chrome-devtools-mcp --headless --isolated --no-usage-statistics --no-performance-crux
The summary put LCP at 3,143 ms, and the breakdown says where it went: 3,006 ms of load duration, almost nothing in TTFB or render delay. That rules out the server and the main thread at once. A second run asked for the LCPDiscovery insight (LCP 3,152 ms that time), which named the image and failed all three of its checks:

The ImageDelivery insight added the size problem: a 4000×2250 file shown at 1905×1072, with 960.5 kB to save. Its own estimate of the gain was modest, 150 to 200 ms of LCP, because it models a normal connection rather than our throttled one. Treat those estimates as a ranking of fixes, not a forecast.
The fix follows straight from the three failed checks: resize and re-encode the image, drop the lazy loading, and mark the hero as high priority. ImageMagick from the 26.04 archive does the conversion. The 24.04 archive ships the previous major release, which has no magick command, so use convert there.
magick img/hero.jpg -resize 1920x -quality 75 img/hero-1920.webp
After swapping the img tag and running the same trace, LCP fell from 3,143 ms to 138 ms. The file shrank from 1,242,217 bytes to 86,072, so even under the same 400k throttle the load duration dropped to 8 ms:

Render delay is now the largest slice at 119 ms, which is the deferred script and first paint, and the next thing to look at if you keep going. Notice also what the agent never needed: a screenshot. Every number came back as text it can reason over.
How do you read console errors and failed requests?
Four tools cover this, and the order matters because the list calls are cheap and the detail calls are not. Have your agent work through them like this:
list_console_messagesreturns every message with an ID.list_network_requestsreturns every request with its status.get_console_messagefetches the full, source-mapped stack for one message.get_network_requestfetches the headers and body for one request.
Each list call took under 6 ms and a few hundred characters on our page, so an agent can afford to call them after every action. The steps file for this section opens the page and asks for message 3.
echo '[{"tool":"new_page","args":{"url":"http://127.0.0.1:8080/"}},{"tool":"list_console_messages","args":{"pageId":"{{page}}"}},{"tool":"get_console_message","args":{"pageId":"{{page}}","msgid":3}},{"tool":"list_network_requests","args":{"pageId":"{{page}}"}}]' > console.json
CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS=1 node mcpc.mjs console.json -- chrome-devtools-mcp --headless --isolated --no-usage-statistics --no-performance-crux
Four errors came back, and the stack for the third is the reason to choose this server. It points at cart.ts:16:36, the TypeScript line that reads price!.amount, not at column 232 of the minified bundle:

The network list closes the loop. Request 4, /api/prices.json, returned 404, so loadPrices() logged its error and handed back an empty list. Then cartTotal() dereferenced a price that was not there. Calling get_network_request on request 4 returned the full request and response headers plus the nginx 404 body, which is what you would check next for a wrong path or a missing rewrite.
How do logpoints and network mocks work?
Logpoints are on by default; the mock tools need --category-network-mocks, which raises the tool count from 33 to 35. A logpoint takes a file:line and an expression, binds through the source map, and survives reloads. Mocks apply to one page, so two tabs can test with and without one side by side. We ran both against the broken cart with this mock body:
echo '[{"sku": "kbd-01", "amount": 100.0}, {"sku": "mouse-02", "amount": 10.0}]' > /tmp/prices-mock.json
The body file sits in /tmp on purpose. When the client does not negotiate MCP roots, the server only reads and writes files under the OS temp directory unless you start it with --allowUnrestrictedPaths or point --filesystemRoot elsewhere. Claude Code can negotiate roots, so if it refuses a mock file there, move the file under your project directory or pass --filesystemRoot. The run set a logpoint on src/cart.ts:16, reloaded, mocked the price API from the file, reloaded again, then swapped the file for an upstream URL:

Read it top to bottom and it tells the whole story. The logpoint bound to app.js:1:215 through the map and printed price: undefined, which confirms the bug without touching the code. With the file mock, both prices resolved and the total rendered as $120.00, the 100 + 2 x 10 our mock defines. With the upstream mock pointing at /api/v2/prices.json, the request showed 200 and the total became $138.00 from the real v2 prices.
The last two lines prove the scoping. A fresh tab opened after all that still showed calculating..., because the mock lived on page 2 only. The server also warns that mocks disable the HTTP cache on that page, so do not compare a mocked trace against an unmocked one and call the difference a speedup.
How does it compare with Playwright MCP and agent-browser?
We installed both alternatives on the same 26.04 VM and measured them with the same client. agent-browser was pinned to the release current on test day, and its install step downloads its own Chrome for Testing:
npm install -g @playwright/mcp@latest [email protected] #https://github.com/vercel-labs/agent-browser/releases
agent-browser install
node mcpc.mjs - -- playwright-mcp --headless --isolated
node mcpc.mjs - -- agent-browser mcp --tools core,network,debug
The first number is what each server costs you before it does any work. That means the tool count and the size of the tools/list schema the client loads into context. agent-browser pages its list, so the client follows the cursor to count all of it.

Then we gave each server the same job on the broken shop page: open it, find the error, and list the failed request. This table puts both measurements side by side:
| Server (flags) | Tools | Schema (approx. tokens) | Same task: calls / reply chars | Error location given |
|---|---|---|---|---|
| chrome-devtools-mcp (default) | 33 | 32,302 chars (8,076) | 4 / 1,154 | cart.ts:16:36 (source-mapped) |
chrome-devtools-mcp --slim | 3 | 1,201 chars (300) | not tested | no console tools |
chrome-devtools-mcp --category-network-mocks | 35 | 35,867 chars (8,967) | see mocks above | source-mapped |
Playwright MCP --headless --isolated | 25 | 21,177 chars (5,294) | 3 / 1,117 | app.js:1:232 (minified) |
agent-browser mcp (core) | 33 | 24,628 chars (6,157) | no console or network tools | n/a |
agent-browser --tools core,network,debug | 82 | 50,216 chars (12,554) | 4 / 6,921 | app.js:1:232 (minified) |
agent-browser --tools all | 160 | 85,771 chars (21,443) | not tested | n/a |
Playwright MCP ran the debugging task in the fewest characters, partly because browser_network_requests hides static assets by default and returned only the 404. Its stack, though, stops at the minified bundle, so the agent has to map app.js:1:232 back to source on its own. The agent-browser core profile has no console or network tools at all. With the debug and network profiles added it found the same error, but its network call alone returned 5,478 characters of JSON with full headers.
On Ubuntu, agent-browser’s downloaded Chrome also failed its first launch with No usable sandbox!, because AppArmor restricts unprivileged user namespaces for binaries without a profile. Pointing AGENT_BROWSER_EXECUTABLE_PATH at /opt/google/chrome/chrome, which Ubuntu’s chrome AppArmor profile covers, got it running. Our agent-browser on Linux guide covers that fix and the CLI side of the tool in detail.
Which browser MCP should you install?
For most people debugging their own front end, install Chrome DevTools MCP and keep it on the default tool set. The source-mapped stack and the trace insights are the two things neither alternative gave us, and they are what turn “the page is broken” into a line number. The 8,000-token schema is the price, and on a long debugging session it is small next to the screenshots and snapshots it saves. Pick by the job:
- Your agent explains a slow LCP, a console error or a failing request on a site you build: Chrome DevTools MCP.
- Your agent clicks through flows, fills forms and checks pages in a fixed context budget: Playwright MCP, which also works with Firefox and WebKit.
- You drive the browser from shell commands more than from MCP, or want saved auth states and sessions: agent-browser.
- You need only open, run a script and screenshot: Chrome DevTools MCP with
--slim, at about 300 tokens.
Running two of them side by side is fine as long as each has its own browser and profile. If raw page fetching speed matters more than DevTools data, a lighter engine such as Lightpanda fits better, and for PDF output alone plain headless Chrome print-to-PDF needs no agent at all.
Setup checklist
Go through these in order on a new box. Each one is a check you can run yourself, and a failure points at the matching section above:
node --versionprints a release inside the engine range (22.12 or newer on 26.04, NodeSource on Ubuntu 24.04).google-chrome --versionprints a stable build from Google’s repository, not the snap.whoamiin the shell that runs Claude Code prints a normal user, never root.claude mcp get chrome-devtoolsshows--headless,--isolatedand both privacy flags.claude mcp listreports the server as Connected.- A test
new_pagecall opens a page, which proves Chrome itself starts. - Your bundles ship source maps, so console stacks point at source lines.
- Port 9222, if you use
--browser-url, listens on 127.0.0.1 only.
Once all eight hold, you are ready to give the agent a real bug. Still deciding whether a browser belongs in your agent’s toolbox at all? Our comparison of MCP, RAG and agent skills covers where each one earns its context, and agent-desktop takes the same idea from the browser to the whole Linux desktop.