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 uids. 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 uids 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)
• Additional details: evaluate_script for data not in accessibility tree

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:

{
  "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.