Chrome DevTools MCP

chrome-devtools-mcp is Google's MCP server that gives coding agents Chrome DevTools: performance traces, Lighthouse audits, network and console inspection, and device emulation. This guide points it at a Browserless cloud browser with --wsEndpoint, so your agent debugs pages in a remote browser instead of launching Chrome on your machine.

Prerequisites

• A Browserless API token from your account dashboard
• Node.js 20.19+ (chrome-devtools-mcp runs locally through npx)
• An MCP client, such as Claude Code or Cursor

How it connects

chrome-devtools-mcp normally launches a local Chrome. With --wsEndpoint, it skips the launch and opens a CDP connection to the WebSocket URL you give it. That's the part that matters for Browserless: the server connects to the exact URL you pass, query string included, rather than discovering tabs through /json/list. Browserless provisions a browser per connection and doesn't expose /json/list, which is why tools built around tab discovery fail against it. The MCP server process still runs on your machine; the browser runs on Browserless.

We tested this setup with chrome-devtools-mcp 1.12.0 against wss://production-sfo.browserless.io. These tools all worked: list_pages, new_page, navigate_page, take_snapshot, take_screenshot, evaluate_script, list_console_messages, list_network_requests, emulate, performance_start_trace, and lighthouse_audit.

Step 1: Pick an authentication method

chrome-devtools-mcp accepts the Browserless API token in either of two ways.

Header (recommended). Pass the token as a Bearer header with --wsHeaders. This keeps the token out of the endpoint URL, so it doesn't end up in logs or error messages that print the endpoint:

npx -y chrome-devtools-mcp@latest \
  --wsEndpoint=wss://production-sfo.browserless.io \
  --wsHeaders='{"Authorization":"Bearer YOUR_API_TOKEN_HERE"}'

Token in the URL. Shorter, and useful for clients that make JSON quoting awkward:

npx -y chrome-devtools-mcp@latest \
  --wsEndpoint="wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE"

You don't need to run either command yourself. Your MCP client starts the server, so the next step registers the same command with the client.

Step 2: Register the server with your client

Claude Code

Add the server with claude mcp add. Everything after -- is the command Claude Code runs:

claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest \
  --wsEndpoint=wss://production-sfo.browserless.io \
  --wsHeaders='{"Authorization":"Bearer YOUR_API_TOKEN_HERE"}'

Add --scope user before the server name to make it available in every project, not only the current one. Run claude mcp list to confirm it's registered, then start a new session.

Cursor and other mcpServers clients

Cursor, Windsurf, Claude Desktop, and most other MCP clients read a mcpServers JSON block. In Cursor, use the global ~/.cursor/mcp.json rather than the project-level .cursor/mcp.json. The config holds your API token, and a project file is easy to commit by accident:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--wsEndpoint=wss://production-sfo.browserless.io",
        "--wsHeaders={\"Authorization\":\"Bearer YOUR_API_TOKEN_HERE\"}"
      ]
    }
  }
}

The inner quotes in --wsHeaders are escaped because the header value is JSON inside a JSON string. If your client chokes on that, use the URL form instead: "--wsEndpoint=wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE" with no --wsHeaders argument.

Restart the client or reload its MCP servers after editing the file.

Expected result

Your client lists chrome-devtools as a connected MCP server, and the agent has its tools available, including list_pages, navigate_page, take_screenshot, performance_start_trace, and lighthouse_audit. A quick check is to ask the agent to call list_pages. It should return at least one page with its ID. If the server shows as failed instead, see the FAQ.

Step 3: Try it on a real page

Ask your agent for something that needs DevTools rather than a plain fetch:

Open https://www.browserless.io, record a performance trace with a reload,
and list the top three insights.

Run a Lighthouse audit on https://docs.browserless.io and summarize the
scores, then list any console errors and failed network requests.

Emulate Slow 3G, load https://www.browserless.io, and take a screenshot
once it finishes loading.

Expected result

For each prompt, the agent calls the matching tools and reports back:

• Trace prompt: performance_start_trace reloads the page, stops on its own, and returns performance insights, which the agent summarizes.
• Lighthouse prompt: lighthouse_audit returns category scores, and list_console_messages and list_network_requests return the page's console output and requests.
• Slow 3G prompt: emulate applies the network throttling, then take_screenshot returns an image of the loaded page.

The browser reports itself as HeadlessChrome on Linux, because it's a Browserless cloud session rather than your desktop Chrome.

Options

Regions

Swap the host to pick a region. The path, headers, and token stay the same:

Region	Endpoint
US West (San Francisco)	wss://production-sfo.browserless.io
Europe (London)	wss://production-lon.browserless.io
Europe (Amsterdam)	wss://production-ams.browserless.io

Pick the region closest to the sites you're debugging if you care about realistic network timings in traces and Lighthouse runs. See connection URLs for the full list.

Session timeout

Browserless closes a session once it reaches its timeout, which drops the MCP server's browser connection. If long traces or multi-step debugging runs disconnect partway through, raise the limit with the timeout query parameter, in milliseconds:

--wsEndpoint="wss://production-sfo.browserless.io?timeout=300000"

The value can't exceed your plan's maximum session time. With the URL token form, add it alongside the token: ?token=YOUR_API_TOKEN_HERE&timeout=300000.

Data sent to Google

chrome-devtools-mcp sends some data to Google by default. Both are independent of Browserless, and both have opt-out flags:

Flag	What it turns off
--no-performance-crux	Sending trace URLs to Google's Chrome UX Report (CrUX) API to fetch field data for performance insights
--no-usage-statistics	Usage statistics collection

Append either flag to the command or args array, for example:

claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest \
  --wsEndpoint=wss://production-sfo.browserless.io \
  --wsHeaders='{"Authorization":"Bearer YOUR_API_TOKEN_HERE"}' \
  --no-performance-crux \
  --no-usage-statistics

Turn off CrUX if you trace internal or staging URLs you don't want leaving your network. You lose the real-user field data in performance insights, but lab data from the trace still comes back.

When to use this vs the Browserless MCP server

Use chrome-devtools-mcp for page-level debugging and performance work: performance traces, Lighthouse audits, network and console inspection, and device or network emulation. It exposes DevTools primitives, so your agent decides what to inspect and when.

Use the Browserless MCP server for scraping, crawling, and handing a multi-step flow to the Browserless agent. Its tools handle stealth, proxies, CAPTCHA solving, and retries per request, which chrome-devtools-mcp doesn't do.

You can register both in the same client. They share the same API token and don't conflict.

FAQ & Troubleshooting

Tool calls fail with a missing pageId argument

In chrome-devtools-mcp 1.12, page-scoped tools such as navigate_page, take_screenshot, and evaluate_script take a pageId. MCP clients normally fill this in themselves by calling list_pages first, which returns the ID of every open page. If you're driving the server from your own MCP client or script, call list_pages (or new_page) and pass the returned ID.

stderr shows Browserless.heartbeat is for non-existing domain 'Browserless'

Ignore it. Browserless sends a heartbeat on its own Browserless CDP domain, and chrome-devtools-mcp logs a Protocol Error because it doesn't recognize that domain. The connection and every tool call keep working.

The connection is rejected or closes immediately

The token didn't reach Browserless. With --wsHeaders, check that the value is valid JSON with double quotes, and that your shell or JSON config didn't strip them. The shell form needs single quotes around the whole object, and the JSON config form needs \" escapes. If you're stuck, switch to the ?token= URL form to rule out quoting.

Can I use this with a community opencode or CDP browser plugin instead?

Community CDP plugins such as opencode-chrome-devtools discover tabs through /json/list and rebuild the WebSocket URL from the host and path, which drops ?token=. Neither works with Browserless. chrome-devtools-mcp avoids both problems because --wsEndpoint connects to the URL you give it as-is. See the opencode guide for the hosted MCP route.

What does a session cost?

The connection is a regular Browserless browser session, so it consumes units based on session time. Close your MCP client, or remove the server, when you're done debugging so the session doesn't stay open. See unit consumption for the breakdown.

Next steps

Browserless MCP server

scraping, crawling, and agent tools with stealth and CAPTCHA solving

Playwright MCP + Browserless

Playwright's navigate, click, and type tools over a Browserless CDP endpoint

Connection URLs

regional endpoints and query parameters for every connection