chrome-devtools-mcp

Exposes Chrome DevTools capabilities through the Model Context Protocol (MCP) using STDIO transport, enabling AI agents to invoke browser operations as structured tool calls. The server implements a single-threaded execution model with Mutex-based synchronization to prevent race conditions during concurrent tool invocations, ensuring deterministic browser state transitions. Requests flow through a standardized MCP schema that maps natural language intents to typed tool parameters, with responses formatted as token-optimized JSON for LLM consumption.

Supports three distinct browser connection strategies (launch new instance, auto-connect to existing, HTTP debug protocol) configured via CLI arguments, with automatic lifecycle management including headless mode, isolated profiles, and custom user data directories. The system implements ensureBrowserLaunched() and ensureBrowserConnected() methods that handle connection establishment, validation, and recovery without requiring manual browser startup. Connection strategy is determined at server initialization and persists for the server's lifetime, enabling both managed and unmanaged browser scenarios.

Reads, sets, and deletes cookies, localStorage, and sessionStorage across the page and domain. The system uses Chrome DevTools Protocol's Storage domain to access persistent storage and the Runtime domain to access in-memory storage (localStorage, sessionStorage). Storage operations are scoped to the current page's origin, preventing cross-origin access. This enables agents to manage authentication state, test storage-dependent behavior, and clear state between test cases.

Manages viewport size, scroll position, and page dimensions. The system uses Chrome DevTools Protocol's Emulation domain to set viewport size and the Runtime domain to control scroll position via window.scrollTo(). Viewport changes trigger page reflow and may affect responsive design behavior. Scroll operations enable agents to access content below the fold and verify lazy-loading behavior.

Provides blocking wait operations for page state changes (navigation, element visibility, network idle, custom conditions). The system uses Chrome DevTools Protocol's Page and Network domains to detect state changes, with configurable timeouts and polling intervals. Wait operations block the agent until the condition is met or timeout is exceeded, enabling agents to synchronize with asynchronous page behavior without explicit polling logic.

Implements graceful error handling for failed operations (selector resolution, navigation timeouts, network errors) with detailed error messages and recovery suggestions. The system catches exceptions from Chrome DevTools Protocol operations and returns structured error responses with error type, message, and context. Failed operations do not crash the server or corrupt browser state, enabling agents to handle errors and retry with different approaches.

Captures structured accessibility trees and DOM snapshots from the current page, extracting semantic information about interactive elements, text content, and page structure in a format optimized for LLM reasoning. The system uses Chrome DevTools Protocol's accessibility domain to build a tree representation of the page, filtering for user-visible elements and computing bounding boxes for spatial reasoning. Snapshots are serialized as JSON with element IDs, roles, labels, and coordinates, enabling agents to understand page structure without visual rendering.

Captures Chrome DevTools performance traces (CPU, memory, network, rendering) and analyzes them using chrome-devtools-frontend components to extract high-level metrics like Largest Contentful Paint (LCP), First Input Delay (FID), and memory usage. The system records traces during page load or user interactions, then parses the trace data to compute performance insights without requiring external APM tools. Traces are formatted as structured JSON with timeline events, metric summaries, and bottleneck identification for agent-driven performance optimization.

Intercepts and logs HTTP/HTTPS requests and responses during page navigation and user interactions, capturing headers, body content, status codes, and timing information. The system uses Chrome DevTools Protocol's Network domain to monitor traffic without modifying requests, enabling agents to verify API calls, detect failed requests, and analyze network behavior. Network logs are formatted as structured JSON with request/response metadata, enabling agents to reason about API interactions and network issues.

Automates user input (clicks, typing, keyboard events) by targeting elements via accessibility selectors, CSS selectors, or XPath expressions. The system resolves selectors to DOM elements, computes bounding boxes, and simulates native browser events (mousedown, mouseup, keydown, keyup) to trigger event handlers. Input automation respects element state (disabled, hidden) and validates that elements are interactable before executing actions, preventing errors from stale or invalid selectors.

Navigates to URLs, handles page load completion, and manages browser history (back, forward, reload). The system uses Chrome DevTools Protocol's Page domain to initiate navigation, wait for load events (domContentLoaded, loadEventFired), and handle navigation timeouts. Navigation is synchronous from the agent's perspective, blocking until the page reaches a stable state (configurable via waitUntil parameter: load, domContentLoaded, networkIdle).

Executes arbitrary JavaScript code in the page context and captures console output (logs, errors, warnings). The system uses Chrome DevTools Protocol's Runtime domain to evaluate expressions, with support for async/await and promise resolution. Console messages are captured via the Console domain and formatted as structured JSON with message type, text, and source location. This enables agents to extract computed values, trigger page logic, and debug JavaScript errors.

Simulates different device types (mobile, tablet, desktop) with specific viewport sizes, user agents, and device capabilities (touch, accelerometer). The system uses Chrome DevTools Protocol's Emulation domain to set device metrics, user agent strings, and feature flags before page load. Emulation is configured at server startup and persists for the server's lifetime, enabling consistent testing across different device profiles without restarting the browser.

Captures full-page or viewport screenshots in PNG or JPEG format, with support for clipping specific regions and capturing elements in different states (normal, hover, focus). The system uses Chrome DevTools Protocol's Page domain to render the page and encode screenshots, with options for full-page capture (scrolls entire page) or viewport-only capture. Screenshots are returned as base64-encoded image data, enabling agents to perform visual analysis or store snapshots for comparison.