diff --git a/README.md b/README.md index 3061d9519..d135a48f2 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 diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 1be6efbd5..584c9b6a7 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -75,3 +75,31 @@ 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` 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`. diff --git a/examples/remote-debugging-9222.mjs b/examples/remote-debugging-9222.mjs new file mode 100644 index 000000000..2c9362b8a --- /dev/null +++ b/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(); +}