chrome-devtools

## Core Concepts **Browser lifecycle**: Browser starts automatically on first tool call using a persistent Chrome profile. Configure via CLI args in the MCP server configuration: `npx chrome-devtools-mcp@latest --help`. Addional tooling can be enabled by providing the following flags: - For extension tooling, use the `--categoryExtensions` flag. - For memory tooling, use the `--memoryDebugging` flag. **Page targeting**: Page-scoped tools require a `pageId` parameter to target a specific page. Use `list_pages` to see available pages and their IDs (e.g. `pageId: 1`), or use the ID returned when creating a page with `new_page`. Note: For `evaluate_script`, `pageId` is required when targeting pages. However, when `--categoryExtensions` is enabled, `pageId` is optional so you can pass `serviceWorkerId` instead to evaluate inside an extension background service worker. **Element interaction**: Use `take_snapshot` to get page structure with element `uid`s. Each element has a unique `uid` for interaction. If an element isn't found, take a fresh snapshot - the element may have been removed or the page changed. ## Workflow Patterns ### Before interacting with a page 1. Navigate: `navigate_page` or `new_page` 2. Wait: `wait_for` to ensure content is loaded if you know what you look for. 3. Snapshot: `take_snapshot` with `pageId` to understand page structure 4. Interact: Use element `uid`s from snapshot for `click`, `fill`, etc., passing the corresponding `pageId`. ### Efficient data retrieval - Use `filePath` parameter for large outputs (screenshots, snapshots, traces) - Use pagination (`pageIdx`, `pageSize`) and filtering (`types`) to minimize data - Set `includeSnapshot: false` on input actions unless you need updated page state ### Tool selection - **Automation/interaction**: `take_snapshot` (text-based, faster, better for automation) - **Visual inspection**: `take_screenshot` (when user needs to see visual state) - **CSS & Styling inspection**: Use `get_css_styles` to inspect matched rules, cascade, and CSS variables. Treat the output as authoritative and complete. - **Additional details**: Use `evaluate_script` for runtime DOM/JS data not available via `get_css_styles` or `take_snapshot`. ### Parallel execution You can send multiple tool calls in parallel, but maintain correct order: navigate → wait → snapshot → interact. ### Testing an extension > **Before proceeding**: Extension tools (`install_extension`, `list_extensions`, etc.) are only available when the MCP server is started with the `--categoryExtensions` flag. If these tools are not in your tool list, stop and ask the user to update their MCP server configuration: > > ```json > { > "mcpServers": { > "chrome-devtools": { > "command": "npx", > "args": ["chrome-devtools-mcp@latest", "--categoryExtensions"] > } > } > } > ``` > > After updating, the user must restart the MCP server (or their AI client) for the change to take effect. 1. **Install**: Use `install_extension` with the path to the unpacked extension. 2. **Identify**: Get the extension ID from the response or by calling `list_extensions`. 3. **Trigger Action**: Use `trigger_extension_action` to open the popup or side panel if applicable. 4. **Verify Service Worker**: Use `evaluate_script` with `serviceWorkerId` (omitting `pageId` and `args`) to check extension state or trigger background actions. When evaluating in a page, pass `pageId` (omitting `serviceWorkerId`). 5. **Verify Page Behavior**: Navigate to a page where the extension operates and use `take_snapshot` to check if content scripts injected elements or modified the page correctly. ## Troubleshooting 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.