troubleshooting
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.
Security Assessment
About troubleshooting
This skill turns the assistant into a diagnostic wizard for the Chrome DevTools MCP server. It targets the frustrating class of failures that occur when browser-automation tools like `list_pages`, `new_page`, or `navigate_page` stop working, or when the MCP server refuses to initialize at all. Rather than guessing, it drives a deterministic, step-by-step triage: locate and read the user's MCP configuration, match the error against a catalogue of known symptoms, consult the upstream troubleshooting documentation, and only then propose a corrected configuration.
The workflow codifies real-world knowledge about the server's quirks. It knows that `Could not find DevToolsActivePort` is specific to the `--autoConnect` feature and requires a running, remote-debugging-enabled Chrome 144+; that a limited tool set usually means the client is enforcing read-only mode; and that extension tools depend on the `--categoryExtensions` flag and launching (not attaching to) Chrome. It searches for config files such as `.mcp.json`, `.claude/settings.json`, and `.vscode/launch.json`, distinguishes flag typos, and prescribes safe verification steps like calling `list_pages` before retrying complex commands. As a last resort it runs read-only diagnostics (`npx chrome-devtools-mcp@latest --help`, verbose `DEBUG=*` logging) and can search the project's GitHub issues with the `gh` CLI.
It is aimed at developers and MCP client users (Claude Desktop, Gemini CLI, VS Code, Codex) who are wiring up browser automation and hitting connection or target errors. The single-file SKILL.md is a self-contained runbook, useful whenever DevTools MCP setup breaks across macOS, Linux containers, or WSL environments.
FAQ
When does this skill activate?
When Chrome DevTools MCP tools like list_pages, new_page, or navigate_page fail, or when the MCP server won't start or initialize.
What does it do first?
It locates and reads your MCP configuration (.mcp.json, .claude/settings.json, .vscode/launch.json, gemini-extension.json, or .gemini/settings.json) to spot bad flags, missing environment variables, or incompatible use of --autoConnect.
Why do I only see a handful of tools?
The MCP client is likely enforcing read-only mode. Only tools annotated readOnlyHint:true are exposed; disable read-only mode (e.g. exit Plan Mode) to access state-modifying tools like click and navigate_page.
What are the prerequisites for --autoConnect?
A running Chrome 144+ with remote debugging enabled via chrome://inspect/#remote-debugging. In sandboxed environments the skill recommends --browser-url instead.
Does it make any changes to my system?
No destructive changes. It reads config, suggests configuration snippets, and only runs read-only diagnostics such as --help and verbose logging, or a gh issue search.
Install troubleshooting
Quick Setup:
- Copy the skill folder to
.claude/skills/ - Claude will automatically detect and use the skill
Repository
chromedevtools/chrome-devtools-mcp