From df246d96eaa08d0dcc0b9b755d7660281e6a3ff0 Mon Sep 17 00:00:00 2001 From: root Date: Fri, 13 Feb 2026 15:16:34 +0800 Subject: [PATCH 1/6] docs: add example for connecting via --browserUrl (9222) --- examples/remote-debugging-9222.mjs | 67 ++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 examples/remote-debugging-9222.mjs diff --git a/examples/remote-debugging-9222.mjs b/examples/remote-debugging-9222.mjs new file mode 100644 index 000000000..1ba5d2bad --- /dev/null +++ b/examples/remote-debugging-9222.mjs @@ -0,0 +1,67 @@ +// Example: connect to a Chrome instance that was started with a remote debugging port. +// +// 1) Start Chrome manually with remote debugging enabled, e.g.: +// macOS: +// /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 +// Linux: +// google-chrome --remote-debugging-port=9222 +// +// 2) Run this script: +// node examples/remote-debugging-9222.mjs +// +// This spawns the MCP server and connects it to http://127.0.0.1:9222 via --browserUrl. +// +// Note: This is intentionally a small template you can adapt for your own MCP client. + +import { spawn } from 'node:child_process'; + +const DEBUG_URL = process.env.CHROME_DEBUG_URL ?? 'http://127.0.0.1:9222'; + +const child = spawn( + 'npx', + ['--yes', 'chrome-devtools-mcp@latest', '--browserUrl', DEBUG_URL], + { + stdio: ['pipe', 'pipe', 'pipe'], + env: { + ...process.env, + CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: 'true', + }, + }, +); + +child.stderr.on('data', (d) => process.stderr.write(d)); + +let buf = ''; +child.stdout.on('data', (d) => { + buf += d.toString('utf8'); + let idx; + while ((idx = buf.indexOf('\n')) !== -1) { + const line = buf.slice(0, idx).trim(); + buf = buf.slice(idx + 1); + if (!line) continue; + try { + const msg = JSON.parse(line); + console.log('←', msg); + // Exit after initialize. + if (msg.id === 1) { + child.kill(); + process.exit(0); + } + } catch { + // ignore non-JSON lines + } + } +}); + +const init = { + jsonrpc: '2.0', + id: 1, + method: 'initialize', + params: { + protocolVersion: '2024-11-05', + capabilities: {}, + clientInfo: { name: 'remote-debugging-9222', version: '0.0.0' }, + }, +}; + +child.stdin.write(JSON.stringify(init) + '\n'); From e1756db674fa9593d7b81e6f32651080c3dc82dd Mon Sep 17 00:00:00 2001 From: root Date: Fri, 13 Feb 2026 15:19:41 +0800 Subject: [PATCH 2/6] docs: add troubleshooting for --browserUrl (remote debugging) --- docs/troubleshooting.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index e9f51c037..0e54128b3 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -71,6 +71,34 @@ ssh -N -L 127.0.0.1:9222:127.0.0.1:9222 @ Point the MCP connection inside the VM to `http://127.0.0.1:9222`. This allows DevTools to reach the host browser without triggering the Host validation error. +### Connecting to a running Chrome instance (remote debugging, 9222) + +If you want `chrome-devtools-mcp` to attach to an existing Chrome instance, start Chrome with remote debugging enabled, then pass `--browserUrl`. + +1. Start Chrome with a remote debugging port: + + - Linux: + ```sh + google-chrome --remote-debugging-port=9222 + ``` + + - macOS: + ```sh + /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 + ``` + +2. Verify the endpoint is reachable: + + - `http://127.0.0.1:9222/json/version` should return JSON + +3. Start the MCP server and point it at the debugging endpoint: + + ```sh + npx --yes chrome-devtools-mcp@latest --browserUrl http://127.0.0.1:9222 + ``` + +See also: `examples/remote-debugging-9222.mjs`. + ### Operating system sandboxes Some MCP clients allow sandboxing the MCP server using macOS Seatbelt or Linux From 44a72cc3785f099548da78f77b33dbe1f3979ec8 Mon Sep 17 00:00:00 2001 From: root Date: Fri, 13 Feb 2026 15:26:32 +0800 Subject: [PATCH 3/6] docs: document attaching to a running Chrome instance --- README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.md b/README.md index 56caf311a..92598ceaf 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,17 @@ Chrome DevTools for reliable automation, in-depth debugging, and performance ana ## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md) | [Design Principles](./docs/design-principles.md) +## Connecting to a running Chrome instance + +If you already have a Chrome instance running with remote debugging enabled (for example started with `--remote-debugging-port=9222`), you can attach `chrome-devtools-mcp` to it instead of launching a new browser. + +- HTTP debugging endpoint (recommended): `--browserUrl http://127.0.0.1:9222` +- WebSocket endpoint (advanced): `--wsEndpoint ws://127.0.0.1:9222/devtools/browser/` + +Quick self-check: `http://127.0.0.1:9222/json/version` should return JSON. + +See example: [`examples/remote-debugging-9222.mjs`](./examples/remote-debugging-9222.mjs). + ## Key features - **Get performance insights**: Uses [Chrome From 8a884cc35e3203ec5377728abd1d25685f6efe00 Mon Sep 17 00:00:00 2001 From: root Date: Fri, 13 Feb 2026 17:01:01 +0800 Subject: [PATCH 4/6] docs: switch remote debugging example to MCP SDK --- examples/remote-debugging-9222.mjs | 76 ++++++++++++------------------ 1 file changed, 29 insertions(+), 47 deletions(-) diff --git a/examples/remote-debugging-9222.mjs b/examples/remote-debugging-9222.mjs index 1ba5d2bad..2c9362b8a 100644 --- a/examples/remote-debugging-9222.mjs +++ b/examples/remote-debugging-9222.mjs @@ -1,4 +1,5 @@ -// Example: connect to a Chrome instance that was started with a remote debugging port. +// Example: connect to a Chrome instance that was started with a remote debugging port, +// using the official MCP TypeScript SDK. // // 1) Start Chrome manually with remote debugging enabled, e.g.: // macOS: @@ -9,59 +10,40 @@ // 2) Run this script: // node examples/remote-debugging-9222.mjs // -// This spawns the MCP server and connects it to http://127.0.0.1:9222 via --browserUrl. +// This starts chrome-devtools-mcp with --browserUrl and connects through MCP stdio. // -// Note: This is intentionally a small template you can adapt for your own MCP client. +// For SDK details, see: +// https://modelcontextprotocol.io/docs/develop/build-client#typescript -import { spawn } from 'node:child_process'; +import { Client } from '@modelcontextprotocol/sdk/client/index.js'; +import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'; const DEBUG_URL = process.env.CHROME_DEBUG_URL ?? 'http://127.0.0.1:9222'; -const child = spawn( - 'npx', - ['--yes', 'chrome-devtools-mcp@latest', '--browserUrl', DEBUG_URL], - { - stdio: ['pipe', 'pipe', 'pipe'], - env: { - ...process.env, - CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: 'true', - }, +const transport = new StdioClientTransport({ + command: 'npx', + args: ['--yes', 'chrome-devtools-mcp@latest', '--browserUrl', DEBUG_URL], + env: { + ...process.env, + CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: 'true', }, + stderr: 'inherit', +}); + +const client = new Client( + { name: 'remote-debugging-9222', version: '0.0.0' }, + { capabilities: {} }, ); -child.stderr.on('data', (d) => process.stderr.write(d)); +try { + await client.connect(transport); -let buf = ''; -child.stdout.on('data', (d) => { - buf += d.toString('utf8'); - let idx; - while ((idx = buf.indexOf('\n')) !== -1) { - const line = buf.slice(0, idx).trim(); - buf = buf.slice(idx + 1); - if (!line) continue; - try { - const msg = JSON.parse(line); - console.log('←', msg); - // Exit after initialize. - if (msg.id === 1) { - child.kill(); - process.exit(0); - } - } catch { - // ignore non-JSON lines - } - } -}); + const { tools } = await client.listTools(); + console.log(`Connected to ${DEBUG_URL}. Found ${tools.length} tools.`); -const init = { - jsonrpc: '2.0', - id: 1, - method: 'initialize', - params: { - protocolVersion: '2024-11-05', - capabilities: {}, - clientInfo: { name: 'remote-debugging-9222', version: '0.0.0' }, - }, -}; - -child.stdin.write(JSON.stringify(init) + '\n'); + for (const tool of tools.slice(0, 10)) { + console.log(`- ${tool.name}`); + } +} finally { + await transport.close(); +} From bae069461d01abf3546171be06084f7967b1205f Mon Sep 17 00:00:00 2001 From: root Date: Mon, 16 Feb 2026 14:21:29 +0800 Subject: [PATCH 5/6] docs: fix Codex MCP add instructions --- README.md | 15 +++++++++++++-- docs/troubleshooting.md | 13 +++++++++++++ 2 files changed, 26 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 92598ceaf..b05f35e2e 100644 --- a/README.md +++ b/README.md @@ -162,12 +162,23 @@ Restart Claude Code to have the MCP server and skills load (check with `/skills` using the standard config from above. You can also install the Chrome DevTools MCP server using the Codex CLI: ```bash -codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest +codex mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest +``` + +Verification: run `codex mcp list` and confirm `chrome-devtools` is listed. + +If you see `error: unexpected argument 'add' found`, your Codex CLI is too old to support `codex mcp add`. +Upgrade Codex, or add the server manually by editing `~/.codex/config.toml`: + +```toml +[mcp_servers.chrome-devtools] +command = "npx" +args = ["-y", "chrome-devtools-mcp@latest"] ``` **On Windows 11** -Configure the Chrome install location and increase the startup timeout by updating `.codex/config.toml` and adding the following `env` and `startup_timeout_ms` parameters: +Configure the Chrome install location and increase the startup timeout by updating `%USERPROFILE%\.codex\config.toml` (usually `C:\Users\\.codex\config.toml`) and adding the following `env` and `startup_timeout_ms` parameters: ``` [mcp_servers.chrome-devtools] diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 0e54128b3..d9362cca9 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -38,6 +38,19 @@ Using `.mcp.json` to debug while using a client: ## Specific problems +### Codex: `error: unexpected argument 'add' found` + +Some older Codex CLI versions don't include the `codex mcp add`/`list` subcommands. + +- Run `codex mcp --help` and check whether it shows `add`. +- If it does not, upgrade Codex, or add the server manually by editing `~/.codex/config.toml`: + +```toml +[mcp_servers.chrome-devtools] +command = "npx" +args = ["-y", "chrome-devtools-mcp@latest"] +``` + ### `Error [ERR_MODULE_NOT_FOUND]: Cannot find module ...` This usually indicates either a non-supported Node version is in use or that the From 74fcf9d394aa45ca754e2b46b62efefbee44bcb5 Mon Sep 17 00:00:00 2001 From: "Molt (OpenClaw)" Date: Mon, 16 Feb 2026 21:54:50 +0800 Subject: [PATCH 6/6] chore: fix linting/formatting for remote debugging example --- docs/troubleshooting.md | 3 +-- eslint.config.mjs | 1 + examples/remote-debugging-9222.mjs | 16 +++++++++++----- 3 files changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index d9362cca9..9389f882f 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -89,8 +89,8 @@ Point the MCP connection inside the VM to `http://127.0.0.1:9222`. This allows D If you want `chrome-devtools-mcp` to attach to an existing Chrome instance, start Chrome with remote debugging enabled, then pass `--browserUrl`. 1. Start Chrome with a remote debugging port: - - Linux: + ```sh google-chrome --remote-debugging-port=9222 ``` @@ -101,7 +101,6 @@ If you want `chrome-devtools-mcp` to attach to an existing Chrome instance, star ``` 2. Verify the endpoint is reachable: - - `http://127.0.0.1:9222/json/version` should return JSON 3. Start the MCP server and point it at the debugging endpoint: diff --git a/eslint.config.mjs b/eslint.config.mjs index db6ddd675..ef88b7ea8 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -32,6 +32,7 @@ export default defineConfig([ 'puppeteer.config.cjs', 'eslint.config.mjs', 'rollup.config.mjs', + 'examples/remote-debugging-9222.mjs', ], }, }, diff --git a/examples/remote-debugging-9222.mjs b/examples/remote-debugging-9222.mjs index 2c9362b8a..93aa80bc8 100644 --- a/examples/remote-debugging-9222.mjs +++ b/examples/remote-debugging-9222.mjs @@ -1,3 +1,9 @@ +/** + * @license + * Copyright 2026 Google LLC + * SPDX-License-Identifier: Apache-2.0 + */ + // Example: connect to a Chrome instance that was started with a remote debugging port, // using the official MCP TypeScript SDK. // @@ -15,8 +21,8 @@ // For SDK details, see: // https://modelcontextprotocol.io/docs/develop/build-client#typescript -import { Client } from '@modelcontextprotocol/sdk/client/index.js'; -import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'; +import {Client} from '@modelcontextprotocol/sdk/client/index.js'; +import {StdioClientTransport} from '@modelcontextprotocol/sdk/client/stdio.js'; const DEBUG_URL = process.env.CHROME_DEBUG_URL ?? 'http://127.0.0.1:9222'; @@ -31,14 +37,14 @@ const transport = new StdioClientTransport({ }); const client = new Client( - { name: 'remote-debugging-9222', version: '0.0.0' }, - { capabilities: {} }, + {name: 'remote-debugging-9222', version: '0.0.0'}, + {capabilities: {}}, ); try { await client.connect(transport); - const { tools } = await client.listTools(); + const {tools} = await client.listTools(); console.log(`Connected to ${DEBUG_URL}. Found ${tools.length} tools.`); for (const tool of tools.slice(0, 10)) {