From 6c0fda3eb07be38903c4fa161cd579da7daea9a0 Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Tue, 3 Mar 2026 11:50:27 +0100 Subject: [PATCH 01/12] feat: add troubleshooting skill definition and expand documentation with details on autoConnect timeouts and extension debugging conflicts. --- docs/troubleshooting.md | 14 +++++++++ skills/troubleshooting/SKILL.md | 50 +++++++++++++++++++++++++++++++++ 2 files changed, 64 insertions(+) create mode 100644 skills/troubleshooting/SKILL.md diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index e9f51c037..31ba2a7a0 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -8,6 +8,7 @@ auto-accept installation prompt. - Find a specific error in the output of the `chrome-devtools-mcp` server. Usually, if your client is an IDE, logs would be in the Output pane. +- Search the [GitHub repository issues and discussions](https://github.com/ChromeDevTools/chrome-devtools-mcp) for help or existing similar problems. ## Debugging @@ -98,3 +99,16 @@ Possible workarounds include: `npx chrome-devtools-mcp --browser-url http://127.0.0.1:9222` - **Use Powershell or Git Bash** instead of WSL. + +### Connection timeouts with `--autoConnect` + +If you are using the `--autoConnect` flag and tools like `list_pages`, `new_page`, or `navigate_page` fail with a timeout (e.g., `ProtocolError: Network.enable timed out` or `The socket connection was closed unexpectedly`), this usually means the MCP server cannot handshake with the running Chrome instance correctly. Ensure: + +1. Chrome 144+ is running. +2. Remote debugging is enabled in Chrome via `chrome://inspect/#remote-debugging`. +3. You have allowed the remote debugging connection prompt in the browser. +4. There is no other MCP server or tool trying to connect to the same debugging port. + +### Conflicts with Extension Debugging + +Extension debugging is not supported when using `--browserUrl` (`--browser-url`) and `--autoConnect`. These options are mutually exclusive to the `--enableCategoryExtensions` (if applicable) or general extension debugging features. Attempting to use them together will result in connection failures or undefined behavior. diff --git a/skills/troubleshooting/SKILL.md b/skills/troubleshooting/SKILL.md new file mode 100644 index 000000000..9ebebbab6 --- /dev/null +++ b/skills/troubleshooting/SKILL.md @@ -0,0 +1,50 @@ +--- +name: troubleshooting +description: Uses Chrome DevTools MCP and documentation to troubleshoot connection and target issues. Trigger this skill when list_pages, new_page, or navigate_page fail, or when the server initialization fails. +--- + +## Troubleshooting Wizard + +You are acting as a troubleshooting wizard to help the user configure and fix their Chrome DevTools MCP server setup. When this skill is triggered (e.g., because `list_pages`, `new_page`, or `navigate_page` failed, or the server wouldn't start), follow this step-by-step diagnostic process: + +### Step 1: Determine the Exact Error + +Identify the exact error message from the failed tool call or the MCP initialization logs. Look for common errors such as: + +- `Target closed` +- `ProtocolError: Network.enable timed out` or `The socket connection was closed unexpectedly` +- `Error [ERR_MODULE_NOT_FOUND]: Cannot find module` +- Any sandboxing or host validation errors. + +### Step 2: Read Known Issues + +Use the `view_file` tool to read the contents of `docs/troubleshooting.md` in the project root to map the error to a known issue. Pay close attention to: + +- Sandboxing restrictions (macOS Seatbelt, Linux containers). +- WSL requirements. +- `--autoConnect` handshakes, timeouts, and requirements. +- Conflicts between `--autoConnect`/`--browser-url` and extension debugging. + +### Step 3: Formulate a Configuration + +Based on the exact error and the user's environment (OS, MCP client), formulate the correct MCP configuration snippet. Check if they need to: + +- Pass `--browser-url=http://127.0.0.1:9222` instead of `--autoConnect` (e.g. if they are in a sandboxed environment like Claude Desktop). +- Remove `--enableCategoryExtensions` if using `--autoConnect`. +- Enable remote debugging in Chrome (`chrome://inspect/#remote-debugging`) and accept the connection prompt. + +_If you are unsure of the user's configuration, ask the user to provide their current MCP server JSON configuration._ + +### Step 4: Run Diagnostic Commands + +If the issue is still unclear, use the `run_command` tool to run diagnostic commands to test the server directly: + +- `npx chrome-devtools-mcp@latest --help` (to verify the installation and Node.js environment) +- Ask the user to run `DEBUG=* npx chrome-devtools-mcp@latest --log-file=/tmp/cdm-test.log` to capture verbose logs if they are attempting to run it from an IDE or different environment. + +### Step 5: Check GitHub for Existing Issues + +If `docs/troubleshooting.md` does not cover the specific error, check if the `gh` (GitHub CLI) tool is available in the environment. If so, use the `run_command` tool to search the GitHub repository for similar issues: +`gh issue list --repo ChromeDevTools/chrome-devtools-mcp --search "" --state all` + +Alternatively, you can recommend that the user checks https://github.com/ChromeDevTools/chrome-devtools-mcp/issues and https://github.com/ChromeDevTools/chrome-devtools-mcp/discussions for help. From b71499b37a11cee9fb2714043e55aa8daf6471de Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Tue, 3 Mar 2026 12:18:21 +0100 Subject: [PATCH 02/12] docs: Simplify troubleshooting skill instructions by removing explicit tool mentions and updating the troubleshooting guide link. --- skills/troubleshooting/SKILL.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/skills/troubleshooting/SKILL.md b/skills/troubleshooting/SKILL.md index 9ebebbab6..683871438 100644 --- a/skills/troubleshooting/SKILL.md +++ b/skills/troubleshooting/SKILL.md @@ -18,7 +18,7 @@ Identify the exact error message from the failed tool call or the MCP initializa ### Step 2: Read Known Issues -Use the `view_file` tool to read the contents of `docs/troubleshooting.md` in the project root to map the error to a known issue. Pay close attention to: +Read the contents of https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md to map the error to a known issue. Pay close attention to: - Sandboxing restrictions (macOS Seatbelt, Linux containers). - WSL requirements. @@ -37,14 +37,14 @@ _If you are unsure of the user's configuration, ask the user to provide their cu ### Step 4: Run Diagnostic Commands -If the issue is still unclear, use the `run_command` tool to run diagnostic commands to test the server directly: +If the issue is still unclear, run diagnostic commands to test the server directly: - `npx chrome-devtools-mcp@latest --help` (to verify the installation and Node.js environment) - Ask the user to run `DEBUG=* npx chrome-devtools-mcp@latest --log-file=/tmp/cdm-test.log` to capture verbose logs if they are attempting to run it from an IDE or different environment. ### Step 5: Check GitHub for Existing Issues -If `docs/troubleshooting.md` does not cover the specific error, check if the `gh` (GitHub CLI) tool is available in the environment. If so, use the `run_command` tool to search the GitHub repository for similar issues: +If https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md does not cover the specific error, check if the `gh` (GitHub CLI) tool is available in the environment. If so, search the GitHub repository for similar issues: `gh issue list --repo ChromeDevTools/chrome-devtools-mcp --search "" --state all` Alternatively, you can recommend that the user checks https://github.com/ChromeDevTools/chrome-devtools-mcp/issues and https://github.com/ChromeDevTools/chrome-devtools-mcp/discussions for help. From 0691d7192bad8f214e7d58ab14148b8cbb96793a Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Tue, 3 Mar 2026 12:36:59 +0100 Subject: [PATCH 03/12] docs: Update troubleshooting guide to recommend and correct usage of `--logFile` for capturing debug logs. --- skills/troubleshooting/SKILL.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/skills/troubleshooting/SKILL.md b/skills/troubleshooting/SKILL.md index 683871438..b7227039f 100644 --- a/skills/troubleshooting/SKILL.md +++ b/skills/troubleshooting/SKILL.md @@ -32,6 +32,7 @@ Based on the exact error and the user's environment (OS, MCP client), formulate - Pass `--browser-url=http://127.0.0.1:9222` instead of `--autoConnect` (e.g. if they are in a sandboxed environment like Claude Desktop). - Remove `--enableCategoryExtensions` if using `--autoConnect`. - Enable remote debugging in Chrome (`chrome://inspect/#remote-debugging`) and accept the connection prompt. +- Add `--logFile ` to capture debug logs for analysis. _If you are unsure of the user's configuration, ask the user to provide their current MCP server JSON configuration._ @@ -40,7 +41,7 @@ _If you are unsure of the user's configuration, ask the user to provide their cu If the issue is still unclear, run diagnostic commands to test the server directly: - `npx chrome-devtools-mcp@latest --help` (to verify the installation and Node.js environment) -- Ask the user to run `DEBUG=* npx chrome-devtools-mcp@latest --log-file=/tmp/cdm-test.log` to capture verbose logs if they are attempting to run it from an IDE or different environment. +- Ask the user to run `DEBUG=* npx chrome-devtools-mcp@latest --logFile=/tmp/cdm-test.log` to capture verbose logs if they are attempting to run it from an IDE or different environment. ### Step 5: Check GitHub for Existing Issues From ef2964160a48013c48516b4cb235dd983e65e00d Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Tue, 3 Mar 2026 12:43:55 +0100 Subject: [PATCH 04/12] docs: Enhance troubleshooting guide with 'Tool not found' error, `--autoConnect` Chrome 144+ requirement, and `startup_timeout_ms` tip for Windows. --- skills/troubleshooting/SKILL.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/skills/troubleshooting/SKILL.md b/skills/troubleshooting/SKILL.md index b7227039f..e6a768ae9 100644 --- a/skills/troubleshooting/SKILL.md +++ b/skills/troubleshooting/SKILL.md @@ -12,6 +12,7 @@ You are acting as a troubleshooting wizard to help the user configure and fix th Identify the exact error message from the failed tool call or the MCP initialization logs. Look for common errors such as: - `Target closed` +- "Tool not found" (check if they are using `--slim` which only enables navigation and screenshot tools). - `ProtocolError: Network.enable timed out` or `The socket connection was closed unexpectedly` - `Error [ERR_MODULE_NOT_FOUND]: Cannot find module` - Any sandboxing or host validation errors. @@ -22,7 +23,7 @@ Read the contents of https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/ - Sandboxing restrictions (macOS Seatbelt, Linux containers). - WSL requirements. -- `--autoConnect` handshakes, timeouts, and requirements. +- `--autoConnect` handshakes, timeouts, and requirements (requires Chrome 144+). - Conflicts between `--autoConnect`/`--browser-url` and extension debugging. ### Step 3: Formulate a Configuration @@ -33,6 +34,7 @@ Based on the exact error and the user's environment (OS, MCP client), formulate - Remove `--enableCategoryExtensions` if using `--autoConnect`. - Enable remote debugging in Chrome (`chrome://inspect/#remote-debugging`) and accept the connection prompt. - Add `--logFile ` to capture debug logs for analysis. +- Increase `startup_timeout_ms` (e.g. to 20000) if using Codex on Windows. _If you are unsure of the user's configuration, ask the user to provide their current MCP server JSON configuration._ From f2d5a6e616e9817afad7dd0400c4d809acc5193c Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Tue, 3 Mar 2026 12:59:51 +0100 Subject: [PATCH 05/12] docs: Clarify that Chrome 144+ must be running for `--autoConnect` and add a verification step for remote debugging. --- docs/troubleshooting.md | 2 +- skills/troubleshooting/SKILL.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 31ba2a7a0..2d52c5616 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -104,7 +104,7 @@ Possible workarounds include: If you are using the `--autoConnect` flag and tools like `list_pages`, `new_page`, or `navigate_page` fail with a timeout (e.g., `ProtocolError: Network.enable timed out` or `The socket connection was closed unexpectedly`), this usually means the MCP server cannot handshake with the running Chrome instance correctly. Ensure: -1. Chrome 144+ is running. +1. Chrome 144+ is **already** running. 2. Remote debugging is enabled in Chrome via `chrome://inspect/#remote-debugging`. 3. You have allowed the remote debugging connection prompt in the browser. 4. There is no other MCP server or tool trying to connect to the same debugging port. diff --git a/skills/troubleshooting/SKILL.md b/skills/troubleshooting/SKILL.md index e6a768ae9..c4243ed78 100644 --- a/skills/troubleshooting/SKILL.md +++ b/skills/troubleshooting/SKILL.md @@ -23,7 +23,7 @@ Read the contents of https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/ - Sandboxing restrictions (macOS Seatbelt, Linux containers). - WSL requirements. -- `--autoConnect` handshakes, timeouts, and requirements (requires Chrome 144+). +- `--autoConnect` handshakes, timeouts, and requirements (requires **running** Chrome 144+). - Conflicts between `--autoConnect`/`--browser-url` and extension debugging. ### Step 3: Formulate a Configuration @@ -32,7 +32,7 @@ Based on the exact error and the user's environment (OS, MCP client), formulate - Pass `--browser-url=http://127.0.0.1:9222` instead of `--autoConnect` (e.g. if they are in a sandboxed environment like Claude Desktop). - Remove `--enableCategoryExtensions` if using `--autoConnect`. -- Enable remote debugging in Chrome (`chrome://inspect/#remote-debugging`) and accept the connection prompt. +- Enable remote debugging in Chrome (`chrome://inspect/#remote-debugging`) and accept the connection prompt. **Ask the user to verify this is enabled if using `--autoConnect`.** - Add `--logFile ` to capture debug logs for analysis. - Increase `startup_timeout_ms` (e.g. to 20000) if using Codex on Windows. From f6cd89610a6b5fbf021a448e534afc088cde1840 Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Tue, 3 Mar 2026 13:16:05 +0100 Subject: [PATCH 06/12] feat: Add an initial troubleshooting step to read and interpret MCP configuration, renumbering subsequent steps. --- skills/troubleshooting/SKILL.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/skills/troubleshooting/SKILL.md b/skills/troubleshooting/SKILL.md index c4243ed78..c3ccda657 100644 --- a/skills/troubleshooting/SKILL.md +++ b/skills/troubleshooting/SKILL.md @@ -7,7 +7,16 @@ description: Uses Chrome DevTools MCP and documentation to troubleshoot connecti You are acting as a troubleshooting wizard to help the user configure and fix their Chrome DevTools MCP server setup. When this skill is triggered (e.g., because `list_pages`, `new_page`, or `navigate_page` failed, or the server wouldn't start), follow this step-by-step diagnostic process: -### Step 1: Determine the Exact Error +### Step 1: Read Configuration + +Ask the user to provide their MCP configuration file content (e.g. `claude_desktop_config.json`, `.vscode/launch.json` or `.mcp.json`). + +Interpret the configuration to identify potential issues such as: +- Incorrect arguments or flags. +- Missing environment variables. +- Usage of `--autoConnect` in incompatible environments. + +### Step 2: Determine the Exact Error Identify the exact error message from the failed tool call or the MCP initialization logs. Look for common errors such as: @@ -17,7 +26,7 @@ Identify the exact error message from the failed tool call or the MCP initializa - `Error [ERR_MODULE_NOT_FOUND]: Cannot find module` - Any sandboxing or host validation errors. -### Step 2: Read Known Issues +### Step 3: Read Known Issues Read the contents of https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md to map the error to a known issue. Pay close attention to: @@ -26,7 +35,7 @@ Read the contents of https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/ - `--autoConnect` handshakes, timeouts, and requirements (requires **running** Chrome 144+). - Conflicts between `--autoConnect`/`--browser-url` and extension debugging. -### Step 3: Formulate a Configuration +### Step 4: Formulate a Configuration Based on the exact error and the user's environment (OS, MCP client), formulate the correct MCP configuration snippet. Check if they need to: @@ -38,14 +47,14 @@ Based on the exact error and the user's environment (OS, MCP client), formulate _If you are unsure of the user's configuration, ask the user to provide their current MCP server JSON configuration._ -### Step 4: Run Diagnostic Commands +### Step 5: Run Diagnostic Commands If the issue is still unclear, run diagnostic commands to test the server directly: - `npx chrome-devtools-mcp@latest --help` (to verify the installation and Node.js environment) - Ask the user to run `DEBUG=* npx chrome-devtools-mcp@latest --logFile=/tmp/cdm-test.log` to capture verbose logs if they are attempting to run it from an IDE or different environment. -### Step 5: Check GitHub for Existing Issues +### Step 6: Check GitHub for Existing Issues If https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md does not cover the specific error, check if the `gh` (GitHub CLI) tool is available in the environment. If so, search the GitHub repository for similar issues: `gh issue list --repo ChromeDevTools/chrome-devtools-mcp --search "" --state all` From b71f6944e699be2695bc039cb2897408ef5b53c2 Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Tue, 3 Mar 2026 13:19:57 +0100 Subject: [PATCH 07/12] docs: Add detailed troubleshooting steps for `Could not find DevToolsActivePort` and other common connection errors. --- skills/troubleshooting/SKILL.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/skills/troubleshooting/SKILL.md b/skills/troubleshooting/SKILL.md index c3ccda657..c377bc6ca 100644 --- a/skills/troubleshooting/SKILL.md +++ b/skills/troubleshooting/SKILL.md @@ -16,9 +16,24 @@ Interpret the configuration to identify potential issues such as: - Missing environment variables. - Usage of `--autoConnect` in incompatible environments. -### Step 2: Determine the Exact Error +### Step 2: Triage Common Connection Errors -Identify the exact error message from the failed tool call or the MCP initialization logs. Look for common errors such as: +Before reading documentation or suggesting configuration changes, check if the error message matches one of the following common patterns. + +#### Error: `Could not find DevToolsActivePort` + +This error is highly specific to the `--autoConnect` feature. It means the MCP server cannot find the file created by a running, debuggable Chrome instance. This is not a generic connection failure. + +Your primary goal is to guide the user to ensure Chrome is running and properly configured. Do not immediately suggest switching to `--browserUrl`. Follow this exact sequence: + +1. **Ask the user to confirm that the correct Chrome version** (e.g., "Chrome Canary" if the error mentions it) is currently running. +2. **If the user confirms it is running, instruct them to enable remote debugging.** Be very specific about the URL and the action: "Please open a new tab in Chrome, navigate to `chrome://inspect/#remote-debugging`, and make sure the 'Enable remote debugging' checkbox is checked." +3. **Once the user confirms both steps, your only next action should be to call the `list_pages` tool.** This is the simplest and safest way to verify if the connection is now successful. Do not retry the original, more complex command yet. +4. **If `list_pages` succeeds, the problem is resolved.** If it still fails with the same error, then you can proceed to the more advanced steps like suggesting `--browserUrl` or checking for sandboxing issues. + +#### Other Common Errors + +Identify other error messages from the failed tool call or the MCP initialization logs: - `Target closed` - "Tool not found" (check if they are using `--slim` which only enables navigation and screenshot tools). From 5188faeba091209dd034e3dc414a6b16d997fa34 Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Tue, 3 Mar 2026 13:36:14 +0100 Subject: [PATCH 08/12] docs: Add troubleshooting guidance for empty profile creation due to typos or misconfiguration. --- skills/troubleshooting/SKILL.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/skills/troubleshooting/SKILL.md b/skills/troubleshooting/SKILL.md index c377bc6ca..8ea4e190d 100644 --- a/skills/troubleshooting/SKILL.md +++ b/skills/troubleshooting/SKILL.md @@ -31,6 +31,13 @@ Your primary goal is to guide the user to ensure Chrome is running and properly 3. **Once the user confirms both steps, your only next action should be to call the `list_pages` tool.** This is the simplest and safest way to verify if the connection is now successful. Do not retry the original, more complex command yet. 4. **If `list_pages` succeeds, the problem is resolved.** If it still fails with the same error, then you can proceed to the more advanced steps like suggesting `--browserUrl` or checking for sandboxing issues. +#### Symptom: Server starts but creates a new empty profile + +If the server starts successfully but `list_pages` returns an empty list or creates a new profile instead of connecting to the existing Chrome instance, check for typos in the arguments. + +- **Check for flag typos:** For example, `--autoBronnect` instead of `--autoConnect`. +- **Verify the configuration:** Ensure the arguments match the expected flags exactly. + #### Other Common Errors Identify other error messages from the failed tool call or the MCP initialization logs: From fb001eec473839811eff4d289793ec616685a698 Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Tue, 3 Mar 2026 14:00:57 +0100 Subject: [PATCH 09/12] Formatting --- skills/troubleshooting/SKILL.md | 1 + 1 file changed, 1 insertion(+) diff --git a/skills/troubleshooting/SKILL.md b/skills/troubleshooting/SKILL.md index 8ea4e190d..ac5b37ccf 100644 --- a/skills/troubleshooting/SKILL.md +++ b/skills/troubleshooting/SKILL.md @@ -12,6 +12,7 @@ You are acting as a troubleshooting wizard to help the user configure and fix th Ask the user to provide their MCP configuration file content (e.g. `claude_desktop_config.json`, `.vscode/launch.json` or `.mcp.json`). Interpret the configuration to identify potential issues such as: + - Incorrect arguments or flags. - Missing environment variables. - Usage of `--autoConnect` in incompatible environments. From 4e75415690338bf4e6af59430ceaecf1406a2c58 Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Tue, 3 Mar 2026 15:07:33 +0100 Subject: [PATCH 10/12] docs: Remove information regarding conflicts between autoConnect/browser-url and extension debugging. --- docs/troubleshooting.md | 4 ---- skills/troubleshooting/SKILL.md | 2 -- 2 files changed, 6 deletions(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 2d52c5616..83b579b04 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -108,7 +108,3 @@ If you are using the `--autoConnect` flag and tools like `list_pages`, `new_page 2. Remote debugging is enabled in Chrome via `chrome://inspect/#remote-debugging`. 3. You have allowed the remote debugging connection prompt in the browser. 4. There is no other MCP server or tool trying to connect to the same debugging port. - -### Conflicts with Extension Debugging - -Extension debugging is not supported when using `--browserUrl` (`--browser-url`) and `--autoConnect`. These options are mutually exclusive to the `--enableCategoryExtensions` (if applicable) or general extension debugging features. Attempting to use them together will result in connection failures or undefined behavior. diff --git a/skills/troubleshooting/SKILL.md b/skills/troubleshooting/SKILL.md index ac5b37ccf..4d2c79d19 100644 --- a/skills/troubleshooting/SKILL.md +++ b/skills/troubleshooting/SKILL.md @@ -56,14 +56,12 @@ Read the contents of https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/ - Sandboxing restrictions (macOS Seatbelt, Linux containers). - WSL requirements. - `--autoConnect` handshakes, timeouts, and requirements (requires **running** Chrome 144+). -- Conflicts between `--autoConnect`/`--browser-url` and extension debugging. ### Step 4: Formulate a Configuration Based on the exact error and the user's environment (OS, MCP client), formulate the correct MCP configuration snippet. Check if they need to: - Pass `--browser-url=http://127.0.0.1:9222` instead of `--autoConnect` (e.g. if they are in a sandboxed environment like Claude Desktop). -- Remove `--enableCategoryExtensions` if using `--autoConnect`. - Enable remote debugging in Chrome (`chrome://inspect/#remote-debugging`) and accept the connection prompt. **Ask the user to verify this is enabled if using `--autoConnect`.** - Add `--logFile ` to capture debug logs for analysis. - Increase `startup_timeout_ms` (e.g. to 20000) if using Codex on Windows. From 0e7dad64b4d755cdc0cdd8d0e026edf3c1e0e86e Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Tue, 3 Mar 2026 15:17:11 +0100 Subject: [PATCH 11/12] docs: update example configuration file names in troubleshooting skill documentation --- skills/troubleshooting/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/troubleshooting/SKILL.md b/skills/troubleshooting/SKILL.md index 4d2c79d19..d02cd7657 100644 --- a/skills/troubleshooting/SKILL.md +++ b/skills/troubleshooting/SKILL.md @@ -9,7 +9,7 @@ You are acting as a troubleshooting wizard to help the user configure and fix th ### Step 1: Read Configuration -Ask the user to provide their MCP configuration file content (e.g. `claude_desktop_config.json`, `.vscode/launch.json` or `.mcp.json`). +Ask the user to provide their MCP configuration file content (e.g. `.claude/settings.json`, `./gemini/settings.json`, or `.mcp.json`). Interpret the configuration to identify potential issues such as: From 28d14c78b02da3f6fad2b06b17270ca5c8b294d3 Mon Sep 17 00:00:00 2001 From: Michael Hablich Date: Tue, 3 Mar 2026 15:26:44 +0100 Subject: [PATCH 12/12] Optimize with skill-creator --- skills/troubleshooting/SKILL.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/skills/troubleshooting/SKILL.md b/skills/troubleshooting/SKILL.md index d02cd7657..1c89ecc28 100644 --- a/skills/troubleshooting/SKILL.md +++ b/skills/troubleshooting/SKILL.md @@ -7,16 +7,18 @@ description: Uses Chrome DevTools MCP and documentation to troubleshoot connecti You are acting as a troubleshooting wizard to help the user configure and fix their Chrome DevTools MCP server setup. When this skill is triggered (e.g., because `list_pages`, `new_page`, or `navigate_page` failed, or the server wouldn't start), follow this step-by-step diagnostic process: -### Step 1: Read Configuration +### Step 1: Find and Read Configuration -Ask the user to provide their MCP configuration file content (e.g. `.claude/settings.json`, `./gemini/settings.json`, or `.mcp.json`). +Your first action should be to locate and read the MCP configuration file. Search for the following files in the user's workspace: `.mcp.json`, `gemini-extension.json`, `.claude/settings.json`, `.vscode/launch.json`, or `.gemini/settings.json`. -Interpret the configuration to identify potential issues such as: +If you find a configuration file, read and interpret it to identify potential issues such as: - Incorrect arguments or flags. - Missing environment variables. - Usage of `--autoConnect` in incompatible environments. +If you cannot find any of these files, only then should you ask the user to provide their configuration file content. + ### Step 2: Triage Common Connection Errors Before reading documentation or suggesting configuration changes, check if the error message matches one of the following common patterns. @@ -72,8 +74,8 @@ _If you are unsure of the user's configuration, ask the user to provide their cu If the issue is still unclear, run diagnostic commands to test the server directly: -- `npx chrome-devtools-mcp@latest --help` (to verify the installation and Node.js environment) -- Ask the user to run `DEBUG=* npx chrome-devtools-mcp@latest --logFile=/tmp/cdm-test.log` to capture verbose logs if they are attempting to run it from an IDE or different environment. +- Run `npx chrome-devtools-mcp@latest --help` to verify the installation and Node.js environment. +- If you need more information, run `DEBUG=* npx chrome-devtools-mcp@latest --logFile=/tmp/cdm-test.log` to capture verbose logs. Analyze the output for errors. ### Step 6: Check GitHub for Existing Issues