docs: Update README with WSL configuration details (#946)

Added workarounds for using chrome-devtools-mcp in WSL.

Drive-by: moved known issues from readme to troubleshooting.
Drive-by: updated skill to link to troubleshooting.
Drive-by: rephrased for clarity.

Author: OrKoN

README.md

@@ -683,11 +683,4 @@ Please consult [these instructions](./docs/debugging-android.md).
 
 ## Known limitations
 
-### Operating system sandboxes
-
-Some MCP clients allow sandboxing the MCP server using macOS Seatbelt or Linux
-containers. If sandboxes are enabled, `chrome-devtools-mcp` is not able to start
-Chrome that requires permissions to create its own sandboxes. As a workaround,
-either disable sandboxing for `chrome-devtools-mcp` in your MCP client or use
-`--browser-url` to connect to a Chrome instance that you start manually outside
-of the MCP client sandbox.
+See [Troubleshooting](./docs/troubleshooting.md).

docs/troubleshooting.md

@@ -55,23 +55,46 @@ This indicates that the browser could not be started. Make sure that no Chrome
 instances are running or close them. Make sure you have the latest stable Chrome
 installed and that [your system is able to run Chrome](https://support.google.com/chrome/a/answer/7100626?hl=en).
 
-### Chrome crashes on macOS when opening Web Bluetooth
+### Chrome crashes on macOS when using Web Bluetooth
 
-On macOS, Chrome launched by an MCP host app may crash with a macOS privacy
-permission violation (TCC, "Transparency, Consent, and Control") when a native
-Bluetooth chooser opens.
+On macOS, Chrome launched by an MCP client application (such as Claude Desktop) may crash when a Web Bluetooth prompt appears. This is caused by a macOS privacy permission violation (TCC).
 
-Grant Bluetooth permission to the MCP host app in
-`System Settings > Privacy & Security > Bluetooth`, then restart the MCP host
-app and Chrome MCP session.
+To resolve this, grant Bluetooth permission to the MCP client application in `System Settings > Privacy & Security > Bluetooth`. After granting permission, restart the client application and start a new MCP session.
 
 ### Remote debugging between virtual machine (VM) and host fails
 
-When connecting DevTools inside a VM to Chrome running on the host, any domain is rejected by Chrome because of host header validation. Tunneling the port over SSH bypasses this restriction. In the VM, run:
+When attempting to connect to Chrome running on a host machine from within a virtual machine (VM), Chrome may reject the connection due to 'Host' header validation. You can bypass this restriction by creating an SSH tunnel from the VM to the host. In the VM, run:
 
 ```sh
 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.
+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.
+
+### Operating system sandboxes
+
+Some MCP clients allow sandboxing the MCP server using macOS Seatbelt or Linux
+containers. If sandboxes are enabled, `chrome-devtools-mcp` is not able to start
+Chrome that requires permissions to create its own sandboxes. As a workaround,
+either disable sandboxing for `chrome-devtools-mcp` in your MCP client or use
+`--browser-url` to connect to a Chrome instance that you start manually outside
+of the MCP client sandbox.
+
+### WSL
+
+By default, `chrome-devtools-mcp` in WSL requires Chrome to be installed within the Linux environment. While it normally attempts to launch Chrome on the Windows side, this currently fails due to a [known WSL issue](https://github.com/microsoft/WSL/issues/14201). Ensure you are using a [Linux distribution compatible with Chrome](https://support.google.com/chrome/a/answer/7100626).
+
+Possible workarounds include:
+
+- **Install Google Chrome in WSL:**
+  - `wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb`
+  - `sudo dpkg -i google-chrome-stable_current_amd64.deb`
+
+- **Use Mirrored networking:**
+  1. Configure [Mirrored networking for WSL](https://learn.microsoft.com/en-us/windows/wsl/networking).
+  2. Start Chrome on the Windows side with:
+     `chrome.exe --remote-debugging-port=9222 --user-data-dir=C:\path\to\dir`
+  3. Start `chrome-devtools-mcp` with:
+     `npx chrome-devtools-mcp --browser-url http://127.0.0.1:9222`
+
+- **Use Powershell or Git Bash** instead of WSL.

skills/chrome-devtools/SKILL.md

@@ -42,3 +42,5 @@ If `chrome-devtools-mcp` is insufficient, guide users to use Chrome DevTools UI:
 
 - https://developer.chrome.com/docs/devtools
 - https://developer.chrome.com/docs/devtools/ai-assistance
+
+If there are errors launching `chrome-devtools-mcp` or Chrome, refer to https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md.