troubleshooting by chromedevtools/chrome-devtools-mcp
npx skills add https://github.com/chromedevtools/chrome-devtools-mcp --skill troubleshooting您将扮演一名故障排查向导,帮助用户配置和修复他们的 Chrome DevTools MCP 服务器设置。当此技能被触发时(例如,因为 list_pages、new_page 或 navigate_page 失败,或者服务器无法启动),请遵循以下分步诊断流程:
您的首要操作是定位并读取 MCP 配置文件。在用户的工作空间中搜索以下文件:.mcp.json、gemini-extension.json、.claude/settings.json、.vscode/launch.json 或 .gemini/settings.json。
如果找到配置文件,请读取并解析它以识别潜在问题,例如:
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
--autoConnect如果找不到任何这些文件,才应要求用户提供其配置文件的内容。
在阅读文档或建议更改配置之前,请检查错误信息是否匹配以下常见模式之一。
Could not find DevToolsActivePort此错误是 --autoConnect 功能特有的。它意味着 MCP 服务器无法找到由正在运行的可调试 Chrome 实例创建的文件。这不是一个通用的连接失败。
您的主要目标是引导用户确保 Chrome 正在运行且配置正确。不要立即建议切换到 --browserUrl。请严格按照以下顺序操作:
chrome://inspect/#remote-debugging,并确保选中 '启用远程调试' 复选框。"list_pages 工具。 这是验证连接现在是否成功的最简单、最安全的方法。暂时不要重试原始的、更复杂的命令。list_pages 成功,则问题已解决。 如果它仍然失败并出现相同的错误,那么您可以继续进行更高级的步骤,例如建议使用 --browserUrl 或检查沙盒问题。如果服务器成功启动,但 list_pages 返回空列表或创建了新配置文件,而不是连接到现有的 Chrome 实例,请检查参数中的拼写错误。
--autoBronnect 而不是 --autoConnect。如果服务器成功启动,但只有有限的工具子集(如 list_pages、get_console_message、lighthouse_audit、take_memory_snapshot)可用,这很可能是因为 MCP 客户端正在强制执行只读模式。
chrome-devtools-mcp 中的所有工具都标注了 readOnlyHint: true(对于安全的、非修改性工具)或 readOnlyHint: false(对于修改浏览器状态的工具,如 emulate、click、navigate_page)。要访问完整的工具套件,用户必须在其 MCP 客户端中禁用只读模式(例如,在 Gemini CLI 中退出 "Plan Mode" 或调整其客户端的工具安全设置)。
从失败的工具调用或 MCP 初始化日志中识别其他错误信息:
Target closed--slim,该标志仅启用导航和截图工具)。ProtocolError: Network.enable timed out 或 The socket connection was closed unexpectedlyError [ERR_MODULE_NOT_FOUND]: Cannot find module阅读 https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md 的内容,将错误映射到已知问题。请密切关注:
--autoConnect 握手、超时和要求(需要正在运行的 Chrome 144+ 版本)。根据确切的错误和用户的环境(操作系统、MCP 客户端),制定正确的 MCP 配置片段。检查他们是否需要:
--browser-url=http://127.0.0.1:9222 而不是 --autoConnect(例如,如果他们处于沙盒环境中,如 Claude Desktop)。chrome://inspect/#remote-debugging)并接受连接提示。如果使用 --autoConnect,请要求用户验证此功能是否已启用。--logFile <absolute_path_to_log_file> 以捕获调试日志进行分析。startup_timeout_ms(例如增加到 20000)。如果您不确定用户的配置,请要求用户提供他们当前的 MCP 服务器 JSON 配置。
如果问题仍然不清楚,请运行诊断命令直接测试服务器:
npx chrome-devtools-mcp@latest --help 以验证安装和 Node.js 环境。DEBUG=* npx chrome-devtools-mcp@latest --logFile=/tmp/cdm-test.log 以捕获详细日志。分析输出以查找错误。如果 https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md 没有涵盖特定错误,请检查环境中是否可用 gh(GitHub CLI)工具。如果可用,请在 GitHub 仓库中搜索类似问题:gh issue list --repo ChromeDevTools/chrome-devtools-mcp --search "<error snippet>" --state all
或者,您可以建议用户查看 https://github.com/ChromeDevTools/chrome-devtools-mcp/issues 和 https://github.com/ChromeDevTools/chrome-devtools-mcp/discussions 以寻求帮助。
每周安装次数
37
仓库
GitHub 星标数
28.5K
首次出现
8 天前
安全审计
已安装于
opencode36
gemini-cli36
amp36
cline36
github-copilot36
codex36
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:
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.
If you find a configuration file, read and interpret it to identify potential issues such as:
--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.
Before reading documentation or suggesting configuration changes, check if the error message matches one of the following common patterns.
Could not find DevToolsActivePortThis 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:
chrome://inspect/#remote-debugging, and make sure the 'Enable remote debugging' checkbox is checked."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.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.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.
--autoBronnect instead of --autoConnect.If the server starts successfully but only a limited subset of tools (like list_pages, get_console_message, lighthouse_audit, take_memory_snapshot) are available, this is likely because the MCP client is enforcing a read-only mode.
All tools in chrome-devtools-mcp are annotated with readOnlyHint: true (for safe, non-modifying tools) or readOnlyHint: false (for tools that modify browser state, like emulate, click, navigate_page). To access the full suite of tools, the user must disable read-only mode in their MCP client (e.g., by exiting "Plan Mode" in Gemini CLI or adjusting their client's tool safety settings).
Identify other error messages from the failed tool call or the MCP initialization logs:
Target closed--slim which only enables navigation and screenshot tools).ProtocolError: Network.enable timed out or The socket connection was closed unexpectedlyError [ERR_MODULE_NOT_FOUND]: Cannot find moduleRead 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:
--autoConnect handshakes, timeouts, and requirements (requires running Chrome 144+).Based on the exact error and the user's environment (OS, MCP client), formulate the correct MCP configuration snippet. Check if they need to:
--browser-url=http://127.0.0.1:9222 instead of --autoConnect (e.g. if they are in a sandboxed environment like Claude Desktop).chrome://inspect/#remote-debugging) and accept the connection prompt. Ask the user to verify this is enabled if using--autoConnect.--logFile <absolute_path_to_log_file> to capture debug logs for analysis.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.
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.DEBUG=* npx chrome-devtools-mcp@latest --logFile=/tmp/cdm-test.log to capture verbose logs. Analyze the output for errors.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 "<error snippet>" --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.
Weekly Installs
37
Repository
GitHub Stars
28.5K
First Seen
8 days ago
Security Audits
Gen Agent Trust HubWarnSocketFailSnykWarn
Installed on
opencode36
gemini-cli36
amp36
cline36
github-copilot36
codex36
Skills CLI 使用指南:AI Agent 技能包管理器安装与管理教程
40,000 周安装