Chrome DevTools MCP Server

The chrome-devtools-mcp package allows AI coding agents (such as Claude, Cursor, Copilot, or Antigravity) to control and inspect a live Chrome browser instance. It functions as a Model-Context-Protocol (MCP) server, providing agents with access to Chrome DevTools for automation, debugging, and performance analysis.

Key capabilities include:

• Performance Insights: Recording traces and extracting insights using Chrome DevTools.
• Advanced Debugging: Analyzing network requests, capturing screenshots, and inspecting browser console messages (including source-mapped stack traces).
• Reliable Automation: Using Puppeteer to perform browser actions with automatic waiting for results.

If your MCP client shares a single server instance across multiple concurrent agents or subagents, use the --experimentalPageIdRouting flag. This flag exposes a pageId on page-scoped tools, allowing each agent to route its tool calls to the specific tab it is currently working with, preventing cross-agent interference.

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--experimentalPageIdRouting"
      ]
    }
  }
}

The server uses a dedicated user data directory for Chrome's stable channel. This directory is reused between runs unless --isolated is used.

Default paths:

• Linux / macOS: $HOME/.cache/chrome-devtools-mcp/chrome-profile
• Windows: %USERPROFILE%\/.cache/chrome-devtools-mcp/chrome-profile

For non-stable channels (like Canary), the channel name is appended to the directory (e.g., chrome-profile-canary).

The CLI operates as a client to a background chrome-devtools-mcp daemon. The daemon uses Unix sockets on Linux/Mac and named pipes on Windows to maintain communication.

Key Behaviors

• Automatic Start: The daemon and the browser start automatically the first time you call a tool (e.g., list_pages) if they are not already running.
• Persistence: The background instance is reused across commands, meaning browser state (cookies, open pages, etc.) is preserved.
• Manual Control: You can manage the lifecycle of the background process using start, stop, and status commands.
• Default Modes: Headless mode and isolated mode are enabled by default. You can disable isolation by providing a --userDataDir flag during start.

# Check if the daemon is running
chrome-devtools status

# Stop the background daemon when finished
chrome-devtools stop

The chrome-devtools skill operates on a specific lifecycle and interaction model:

Browser Lifecycle

The browser starts automatically on the first tool call using a persistent Chrome profile.

Page Selection

Tools operate on the currently selected page. You must manage context using:

1. list_pages: To see all available pages.
2. select_page: To switch the active context to a specific page.

Element Interaction

Interaction is driven by unique identifiers. Use take_snapshot to retrieve the page structure. Each element in the snapshot contains a unique uid. Use these uids for interaction tools like click or fill.

Note: If an element is not found, the page state may have changed. You should take a fresh snapshot to get updated uids before retrying.

When debugging LCP, the following element types are candidates for the Largest Contentful Paint metric:

• <img> elements: For animated content like GIFs, the first frame presentation time is used.
• <image> elements: Specifically those located inside an <svg> element.
• <video> elements: The metric uses either the poster image load time or the first frame presentation time, whichever occurs earlier.
• Background images: Any element that loads a background image via the url() CSS property.
• Block-level elements: Elements that contain text nodes or children that are inline-level text elements.

When debugging accessibility, distinguish between the DOM and the Accessibility Tree. While the DOM represents the full HTML structure, the Accessibility Tree represents what assistive technologies (like screen readers) actually 'see'.

Key distinction: Visual hiding techniques behave differently. For example, CSS opacity: 0 keeps an element in the accessibility tree, whereas display: none or aria-hidden="true" removes it. Use the take_snapshot tool to retrieve the accessibility tree, as it is the most reliable source of truth for semantic structure.

Chromium-based browsers apply specific heuristics to ignore elements that do not contribute meaningful content to the user experience. When analyzing LCP, be aware that the following are typically excluded:

• Elements with an opacity of 0.
• Elements that cover the full viewport (these are often treated as background elements).
• Placeholder images or images with low entropy.

LCP size calculations depend on the type of element being measured:

• General Visible Area: The size is determined by what is visible within the viewport. Portions that extend outside the viewport, are clipped, or are part of an overflow do not count.
• Image Elements: The size is the smaller of either the visible size or the intrinsic size.
• Text Elements: The size is defined as the smallest rectangle that contains all text nodes.
• Exclusions: When calculating size, margin, padding, and borders are not included.
• Text Containment: Every text node is attributed to its closest block-level ancestor element for size calculation.