docs: add example for connecting to existing Chrome via --browserUrl

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/<id>`
+
+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

docs/troubleshooting.md

@@ -75,3 +75,31 @@ ssh -N -L 127.0.0.1:9222:127.0.0.1:9222 <user>@<host-ip>
 
 Point the MCP connection inside the VM to `http://127.0.0.1:9222` and DevTools
 will reach the host browser without triggering the Host validation.
+
+### 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`.

examples/remote-debugging-9222.mjs

@@ -0,0 +1,49 @@
+// 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:
+//      /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 starts chrome-devtools-mcp with --browserUrl and connects through MCP stdio.
+//
+// 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';
+
+const DEBUG_URL = process.env.CHROME_DEBUG_URL ?? 'http://127.0.0.1:9222';
+
+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: {} },
+);
+
+try {
+  await client.connect(transport);
+
+  const { tools } = await client.listTools();
+  console.log(`Connected to ${DEBUG_URL}. Found ${tools.length} tools.`);
+
+  for (const tool of tools.slice(0, 10)) {
+    console.log(`- ${tool.name}`);
+  }
+} finally {
+  await transport.close();
+}