| name | chrome-mcp |
| description | Use Chrome DevTools MCP for reliable Chrome automation, especially when the bundled Chrome extension cannot switch tabs, click controls, capture screenshots, inspect DOM/network state, download files, or control an existing Chrome session. Also use when setting up, verifying, or debugging the ChromeDevTools/chrome-devtools-mcp server in Codex. |
Chrome MCP
Overview
Use the chrome-devtools MCP server before giving up on Chrome automation when the bundled @chrome or Browser extension is flaky. Prefer it for real DevTools-backed page inspection, tab/page selection, screenshots, clicks, downloads, console/network debugging, and publisher-site workflows that need reliable visible Chrome control.
Setup Check
This plugin ships an equivalent ./.mcp.json server entry. If installing the skill manually instead of through the plugin, add this server to the user's Codex MCP config:
[mcp_servers.chrome-devtools]
command = "cmd"
args = ["/c", "npx", "-y", "chrome-devtools-mcp@latest", "--autoConnect", "--experimentalPageIdRouting", "--no-usage-statistics"]
startup_timeout_sec = 60
The server uses --autoConnect so it can attach to the user's real Chrome profile instead of launching a separate isolated browser. That requires:
- Chrome 144 or newer.
- Chrome remote debugging enabled from
chrome://inspect/#remote-debugging.
- First-time setup: open
chrome://inspect/#remote-debugging in the user's normal Chrome profile and enable/allow remote debugging there.
- Each time Chrome DevTools MCP attaches to the real Chrome profile, Chrome may show a visible prompt asking the user to allow remote debugging/control. The user must manually accept that prompt; do not try to bypass it or switch to another browser surface.
- A fresh Codex session after editing MCP config, because MCP tools are loaded at session startup.
If Chrome DevTools MCP tools are not visible, ask the user to restart Codex or open a new Codex session after enabling remote debugging.
If the MCP tools are visible but list_pages cannot connect, or reports a missing DevToolsActivePort, tell the user to open chrome://inspect/#remote-debugging, enable/allow remote debugging, and accept the visible remote-control confirmation prompt in Chrome. Retry list_pages only after the user confirms the prompt was accepted.
Tool Discovery
At the start of a Chrome MCP task, search for the tools:
chrome-devtools list pages
chrome-devtools navigate click screenshot
Use the exposed chrome-devtools MCP tools directly once they appear. Do not continue using the bundled Chrome extension for the same interaction if it has already shown tab switching, click, DOM, or screenshot failures.
Workflow
- List pages/tabs first and choose the target by URL/title.
- Select or bring the target page forward if the tool exposes a page selection primitive.
- Capture a screenshot or DOM snapshot before clicking.
- Click controls through DevTools MCP and verify the resulting URL, page title, download event, or new file.
- For downloads, monitor the user's Downloads folder, verify
%PDF- or expected file signatures, then move/rename only after verification.
- Keep one browser task per paper or site transaction when downloads, SSO, CAPTCHAs, or native save dialogs are involved.
Paper Download Notes
For scholarly downloads, combine this skill with chrome-paper-download:
- Use Chrome DevTools MCP as the browser-control surface.
- Keep publisher, Google Scholar, SSO, citation export, PDF viewer, and download actions inside the user's Chrome session.
- Do not replace the browser workflow with raw HTTP or headless scraping.
- If an SSO login, 2FA, CAPTCHA image/audio/text challenge, or password prompt appears, pause for the user.
Failure Handling
If --autoConnect fails:
- Confirm Chrome remote debugging is enabled at
chrome://inspect/#remote-debugging.
- Ask the user to manually accept Chrome's visible remote debugging/control confirmation prompt if it appears.
- If the error mentions
DevToolsActivePort, treat it as remote debugging not yet enabled/confirmed for the real Chrome profile, not as permission to fall back to headless Chrome.
- Confirm Chrome version is at least 144.
- Restart Codex so the MCP server is reloaded.
- If attaching to the real profile is not required, temporarily remove
--autoConnect from the MCP args so the server launches a separate non-headless Chrome profile.
