From cdc16cb70bae8ff3abd97f03152437e3637dc98f Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Fri, 10 Oct 2025 11:11:52 +0200 Subject: [PATCH 1/4] docs: Add step-by-step guide for connecting to running Chrome instance (#140) --- README.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/README.md b/README.md index 032afd8e..b26e40e5 100644 --- a/README.md +++ b/README.md @@ -328,6 +328,83 @@ all instances of `chrome-devtools-mcp`. Set the `isolated` option to `true` to use a temporary user data dir instead which will be cleared automatically after the browser is closed. +### Connecting to a running Chrome instance + +You can connect to a running Chrome instance by using the `--browser-url` option. This is useful if you want to use your existing Chrome profile or if you are running the MCP server in a sandboxed environment that does not allow starting a new Chrome instance. + +Here is a step-by-step guide on how to connect to a running Chrome Stable instance: + +**Step 1: Configure the MCP client** + +Add the `--browser-url` option to your MCP client configuration. The value of this option should be the URL of the running Chrome instance, including the port number. + +```json +{ + "mcpServers": { + "chrome-devtools": { + "command": "npx", + "args": [ + "chrome-devtools-mcp@latest", + "--browser-url=http://localhost:9222" + ] + } + } +} +``` + +**Step 2: Start the Chrome browser** + +Start the Chrome browser with the remote debugging port enabled. Make sure to close any running Chrome instances before starting a new one with the debugging port enabled. + +**macOS** + +```bash +/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 +``` + +**Linux** + +```bash +/usr/bin/google-chrome --remote-debugging-port=9222 +``` + +**Windows** + +```bash +"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 +``` + +**Step 3: Use a non-default user data directory** + +For security reasons, Chrome requires you to use a non-default user data directory when enabling the remote debugging port. You can specify a custom directory using the `--user-data-dir` flag. This ensures that your regular browsing profile and data are not exposed to the debugging session. + +**macOS** + +```bash +/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable +``` + +**Linux** + +```bash +/usr/bin/google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable +``` + +**Windows** + +```bash +"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="%TEMP%\chrome-profile-stable" +``` + +> [!WARNING] +> Enabling the remote debugging port opens up a debugging port on the running browser instance. Any application on your machine can connect to this port and control the browser. Make sure that you are not browsing any sensitive websites while the debugging port is open. + +**Step 4: Ensure the ports are the same** + +The port number in the `--browser-url` option in your MCP client configuration must be the same as the port number you used to start the Chrome browser. + +For more details on remote debugging, see the [Chrome DevTools documentation](https://developer.chrome.com/docs/devtools/remote-debugging/). + ## Known limitations ### Operating system sandboxes From 11c2ba432a699d66caa9af6c1fae515b8d41e650 Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Fri, 10 Oct 2025 13:33:54 +0200 Subject: [PATCH 2/4] Merge 2 and 3 --- README.md | 22 +--------------------- 1 file changed, 1 insertion(+), 21 deletions(-) diff --git a/README.md b/README.md index b26e40e5..4d1c1110 100644 --- a/README.md +++ b/README.md @@ -356,26 +356,6 @@ Add the `--browser-url` option to your MCP client configuration. The value of th Start the Chrome browser with the remote debugging port enabled. Make sure to close any running Chrome instances before starting a new one with the debugging port enabled. -**macOS** - -```bash -/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 -``` - -**Linux** - -```bash -/usr/bin/google-chrome --remote-debugging-port=9222 -``` - -**Windows** - -```bash -"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 -``` - -**Step 3: Use a non-default user data directory** - For security reasons, Chrome requires you to use a non-default user data directory when enabling the remote debugging port. You can specify a custom directory using the `--user-data-dir` flag. This ensures that your regular browsing profile and data are not exposed to the debugging session. **macOS** @@ -399,7 +379,7 @@ For security reasons, Chrome requires you to use a non-default user data directo > [!WARNING] > Enabling the remote debugging port opens up a debugging port on the running browser instance. Any application on your machine can connect to this port and control the browser. Make sure that you are not browsing any sensitive websites while the debugging port is open. -**Step 4: Ensure the ports are the same** +**Step 3: Ensure the ports are the same** The port number in the `--browser-url` option in your MCP client configuration must be the same as the port number you used to start the Chrome browser. From b6386b3db4244b743c9dcab4647a58c9cb8e6836 Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Fri, 10 Oct 2025 15:52:54 +0200 Subject: [PATCH 3/4] docs: improve clarity and add a warning to the Chrome DevTools MCP README. --- README.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 4d1c1110..61651ec3 100644 --- a/README.md +++ b/README.md @@ -336,7 +336,7 @@ Here is a step-by-step guide on how to connect to a running Chrome Stable instan **Step 1: Configure the MCP client** -Add the `--browser-url` option to your MCP client configuration. The value of this option should be the URL of the running Chrome instance, including the port number. +Add the `--browser-url` option to your MCP client configuration. The value of this option should be the URL of the running Chrome instance. `http://localhost:9222` is a common default. ```json { @@ -354,9 +354,12 @@ Add the `--browser-url` option to your MCP client configuration. The value of th **Step 2: Start the Chrome browser** -Start the Chrome browser with the remote debugging port enabled. Make sure to close any running Chrome instances before starting a new one with the debugging port enabled. +> [!WARNING] +> Enabling the remote debugging port opens up a debugging port on the running browser instance. Any application on your machine can connect to this port and control the browser. Make sure that you are not browsing any sensitive websites while the debugging port is open. + +Start the Chrome browser with the remote debugging port enabled. Make sure to close any running Chrome instances before starting a new one with the debugging port enabled. The port number you choose must be the same as the one you specified in the `--browser-url` option in your MCP client configuration. -For security reasons, Chrome requires you to use a non-default user data directory when enabling the remote debugging port. You can specify a custom directory using the `--user-data-dir` flag. This ensures that your regular browsing profile and data are not exposed to the debugging session. +For security reasons, Chrome requires you to use a non-default user data directory when enabling the remote debugging port. You can specify a custom directory using the `--user-data-dir` flag. This ensures that your regular browsing profile and data are not exposed to the debugging session. Consult [this blog post](https://developer.chrome.com/blog/remote-debugging-port) for more details. **macOS** @@ -376,12 +379,15 @@ For security reasons, Chrome requires you to use a non-default user data directo "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="%TEMP%\chrome-profile-stable" ``` -> [!WARNING] -> Enabling the remote debugging port opens up a debugging port on the running browser instance. Any application on your machine can connect to this port and control the browser. Make sure that you are not browsing any sensitive websites while the debugging port is open. +**Step 3: Test your setup** -**Step 3: Ensure the ports are the same** +After configuring the MCP client and starting the Chrome browser, you can test your setup by running a simple prompt in your MCP client: + +``` +Check the performance of https://developers.chrome.com +``` -The port number in the `--browser-url` option in your MCP client configuration must be the same as the port number you used to start the Chrome browser. +Your MCP client should connect to the running Chrome instance and receive a performance report. For more details on remote debugging, see the [Chrome DevTools documentation](https://developer.chrome.com/docs/devtools/remote-debugging/). From c4aa4519b1f1d5540bac5ac9675f0d559dc2dbbf Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Fri, 10 Oct 2025 16:02:47 +0200 Subject: [PATCH 4/4] docs: update link to Chrome remote debugging port blog post --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 61651ec3..4c5e7a50 100644 --- a/README.md +++ b/README.md @@ -359,7 +359,7 @@ Add the `--browser-url` option to your MCP client configuration. The value of th Start the Chrome browser with the remote debugging port enabled. Make sure to close any running Chrome instances before starting a new one with the debugging port enabled. The port number you choose must be the same as the one you specified in the `--browser-url` option in your MCP client configuration. -For security reasons, Chrome requires you to use a non-default user data directory when enabling the remote debugging port. You can specify a custom directory using the `--user-data-dir` flag. This ensures that your regular browsing profile and data are not exposed to the debugging session. Consult [this blog post](https://developer.chrome.com/blog/remote-debugging-port) for more details. +For security reasons, [Chrome requires you to use a non-default user data directory](https://developer.chrome.com/blog/remote-debugging-port) when enabling the remote debugging port. You can specify a custom directory using the `--user-data-dir` flag. This ensures that your regular browsing profile and data are not exposed to the debugging session. **macOS**