Related Pages

Related topics: Installation and Setup, System Architecture, Configuration Reference

Project Overview

Introduction

The chrome-devtools-mcp project is a Model Context Protocol (MCP) server and command-line interface (CLI) for Chrome DevTools. It provides a comprehensive bridge that enables AI assistants, automated testing systems, and developer tools to programmatically control and interact with Chrome browser instances through Chrome DevTools Protocol (CDP).

Sources: AGENTS.md

Core Purpose and Scope

The project serves as an abstraction layer that exposes Chrome DevTools capabilities as MCP tools, making browser automation accessible through a standardized protocol. This enables use cases including:

• AI-Powered Browser Automation: Allowing language models to control browsers for research, testing, and data extraction
• Performance Analysis: Capturing traces, analyzing Largest Contentful Paint (LCP), and measuring page load metrics
• Accessibility Auditing: Running automated accessibility checks and inspecting the accessibility tree
• End-to-End Testing: Automating user interactions including navigation, form filling, and element inspection
• WebMCP Tool Execution: Running custom tools exposed by web pages through the WebMCP protocol

Sources: skills/chrome-devtools-cli/SKILL.md

Architecture Overview

The system follows a layered architecture with distinct components:

graph TD
    A[CLI / AI Agent] --> B[MCP Server]
    B --> C[Tool Registry]
    C --> D[CDP Client]
    D --> E[Chrome Browser]
    F[WebMCP Tools] -.-> B
    G[PageCollector] --> H[Event Listeners]
    H --> E

Component Layers

Sources: src/McpResponse.ts and src/PageCollector.ts

Tool Categories

The project organizes tools into the following categories:

Sources: skills/chrome-devtools-cli/SKILL.md

Page Management System

The PageCollector class manages multiple browser pages using Chrome's target lifecycle:

graph LR
    A[Browser Instance] -->|targetcreated| B[PageCollector]
    A -->|targetdestroyed| B
    B --> C[WeakMap Storage]
    C --> D[Navigation History]
    D --> E[Resource Tracking]

Key characteristics:

• Multiple Page Support: Manages several open pages simultaneously
• Navigation History: Stores up to 3 recent navigations per page (maxNavigationSaved = 3)
• Resource Tracking: Collects resources per navigation sub-list
• Event-Driven: Listens to Chrome target lifecycle events

Sources: src/PageCollector.ts

Tool Definition System

The tool system uses TypeScript and Zod for schema validation. Two primary tool types exist:

Global Tools

Tools that operate independently of page context:

export function defineTool<Schema extends zod.ZodRawShape>(
  definition: ToolDefinition<Schema>,
): DefinedTool<Schema>;

Page-Scoped Tools

Tools that require a selected page context:

export function definePageTool<Schema extends zod.ZodRawShape>(
  definition: PageToolDefinition<Schema>,
): DefinedPageTool<Schema>;

#### Page Scope Schema

export const pageIdSchema = {
  pageId: zod.number().optional().describe('Targets a specific page by ID.'),
};

#### Timeout Schema

export const timeoutSchema = {
  timeout: zod
    .number()
    .int()
    .optional()
    .describe(
      `Maximum wait time in milliseconds. If set to 0, the default timeout will be used.`,
    ),
};

Sources: src/tools/ToolDefinition.ts

WebMCP Integration

WebMCP enables web pages to expose custom tools that can be discovered and executed by this MCP server. The system provides two tools:

export const listWebMcpTools = definePageTool({
  name: 'list_webmcp_tools',
  description: `Lists all WebMCP tools the page exposes.`,
  annotations: {
    category: ToolCategory.WEBMCP,
    readOnlyHint: true,
  },
  schema: {},
  blockedByDialog: false,
});

Sources: src/tools/webmcp.ts

Navigation Tools

The project provides comprehensive navigation capabilities:

Basic Navigation

Navigation Options

interface NavigationOptions {
  url?: string;                    // Target URL
  type?: 'navigate' | 'back' | 'reload';
  timeout?: number;                // Navigation timeout in ms
  ignoreCache?: boolean;          // Ignore cache on reload
  bringToFront?: boolean;         // Bring page to front after selection
  background?: boolean;            // Create page in background
  isolatedContext?: string;       // Isolated world context name
  handleBeforeUnload?: 'accept' | 'dismiss';
  initScript?: string;             // JavaScript to run after navigation
}

Sources: skills/chrome-devtools-cli/SKILL.md

Performance Analysis Tools

Tracing Workflow

graph LR
    A[performance_start_trace] --> B[User Interactions]
    B --> C[performance_stop_trace]
    C --> D[Trace Analysis]
    D --> E[insight_analyze_insight]

Available Performance Tools

LCP Optimization Debugging

The project includes specialized tools for debugging Largest Contentful Paint issues:

1. Identify LCP Element: Extract element tag, id, className, URL, and timing data
2. Audit Common Issues: Check for lazy-loaded images in viewport, missing fetchpriority
3. Optimization Strategies: Preload, fetchpriority, modern formats, critical CSS inlining

Sources: skills/debug-optimize-lcp/SKILL.md and skills/debug-optimize-lcp/references/optimization-strategies.md

Accessibility Debugging Tools

Core A11y Workflow

graph TD
    A[Lighthouse Audit] --> B{Analyze Score}
    B -->|Score < 1| C[Review Failed Audits]
    B -->|Pass| D[Snapshot Tree]
    C --> D
    D --> E[Check Semantics]
    E --> F[Verify Labels]
    F --> G[Test Keyboard Nav]

Key Capabilities

• Automated Audits: Run Lighthouse accessibility audits with JSON report output
• Accessibility Tree Inspection: Use take_snapshot to capture the semantic structure
• Semantic Analysis: Verify heading hierarchy, ARIA landmarks
• Label Verification: Ensure all form inputs have associated labels
• Keyboard Navigation: Test focus management using press_key with Tab navigation

Sources: skills/a11y-debugging/SKILL.md

Evaluation Framework

The project includes a test framework for verifying tool usage correctness:

export interface TestScenario {
  prompt: string;           // The prompt to send to the model
  maxTurns: number;        // Maximum conversation turns
  htmlRoute?: {            // Optional custom HTML for testing
    path: string;
    htmlContent: string;
  };
  expectations: (calls: ToolCall[]) => void;  // Validation function
}

Example Test Scenarios

Sources: scripts/eval_scenarios/snapshot_test.ts and scripts/eval_scenarios/performance_test.ts

Response Format

The MCP response system supports structured output with multiple content sections:

structuredContent.webmcpTools = data.webmcpTools.map(
  ({name, description, inputSchema, annotations}) => ({
    name,
    description,
    inputSchema,
    annotations,
  }),
);

Sources: src/McpResponse.ts

Build and Development

Available npm Scripts

TypeScript Guidelines

The project enforces strict TypeScript practices:

• No any type: Use proper generics and unknown types
• No as keyword: Use type guards and type predicates
• No ! operator: Use explicit null checks
• No // @ts-ignore: Fix actual type issues
• Prefer for..of: Over forEach for better type inference

Sources: AGENTS.md

Installation

The CLI can be installed globally via npm:

npm i chrome-devtools-mcp@latest -g
chrome-devtools status  # Verify installation

Troubleshooting tips include ensuring the global npm bin directory is in PATH and avoiding sudo by using node version managers.

Sources: skills/chrome-devtools-cli/references/installation.md

Summary

The chrome-devtools-mcp project provides a powerful bridge between AI assistants and Chrome DevTools, enabling programmatic browser control through a well-structured MCP interface. Its comprehensive tool system covers navigation, inspection, interaction, performance analysis, and accessibility auditing, while the WebMCP integration allows dynamic tool exposure from web pages. The TypeScript-based architecture with Zod schema validation ensures type safety and developer productivity, making it suitable for both automated testing and AI-driven browser interactions.

Related Pages

Related topics: Project Overview, Configuration Reference

Installation and Setup

This page covers all methods for installing and configuring the chrome-devtools-mcp project, including global CLI usage, local development setup, and MCP server integration.

Overview

The chrome-devtools-mcp project provides two primary interfaces:

1. CLI Tool (chrome-devtools) - A command-line interface for terminal-based browser automation
2. MCP Server - A Model Context Protocol server for integrating Chrome DevTools into AI assistants

The installation approach depends on your use case:

Sources: skills/chrome-devtools-cli/references/installation.md:1-5

Prerequisites

Node.js Version Requirement

The project requires a specific Node.js version defined in .nvmrc. Before installation, ensure you have the correct version:

# Check the required Node.js version
cat .nvmrc

Using a Node version manager (such as nvm) is strongly recommended to avoid permission errors and manage multiple Node versions.

Sources: CONTRIBUTING.md:31-35

System Requirements

• Operating System: macOS, Linux, or Windows with WSL
• Chrome/Chromium: Chrome browser must be installed on the system
• npm: Node Package Manager (included with Node.js)
• Optional: ffmpeg (required only for experimental screencast feature)

Method 1: Global CLI Installation

Installation

Install the package globally to make the chrome-devtools command available system-wide:

npm i chrome-devtools-mcp@latest -g

Sources: skills/chrome-devtools-cli/references/installation.md:5

Verification

After installation, verify the setup:

chrome-devtools status

A successful output indicates the CLI is properly installed and accessible.

Sources: skills/chrome-devtools-cli/references/installation.md:7

Method 2: Local Development Setup

For contributing to the project or running the latest development version:

Workflow Diagram

graph TD
    A[Clone Repository] --> B[Check Node.js Version]
    B --> C{nvm installed?}
    C -->|No| D[Install nvm]
    C -->|Yes| E[Run nvm use]
    D --> E
    E --> F[Run npm ci]
    F --> G[Run npm run build]
    G --> H[Verify with npm run test]
    H --> I[Setup Complete]

Step-by-Step Instructions

#### 1. Clone the Repository

git clone https://github.com/ChromeDevTools/chrome-devtools-mcp.git
cd chrome-devtools-mcp

Sources: CONTRIBUTING.md:33-36

#### 2. Set Node.js Version

nvm use

This reads the version from .nvmrc and switches to the correct Node.js version.

#### 3. Install Dependencies

npm ci

The npm ci command performs a clean install using the exact versions from package-lock.json, ensuring consistency across environments.

Sources: CONTRIBUTING.md:36

#### 4. Build the Project

npm run build

This command runs TypeScript compilation (tsc) and verifies the build succeeds. The build output is placed in the build/ directory.

Sources: AGENTS.md:5

Available npm Scripts

Sources: AGENTS.md:5-10

Method 3: MCP Server Configuration

For integrating with AI assistants that support the Model Context Protocol.

Configuration Schema

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "node",
      "args": ["/path-to/build/src/bin/chrome-devtools-mcp.js"]
    }
  }
}

Sources: CONTRIBUTING.md:45-51

MCP Server Binary Location

After building, the MCP server executable is located at:

build/src/bin/chrome-devtools-mcp.js

Using with Inspector

Test the MCP server using the official inspector:

npx @modelcontextprotocol/inspector node /build/src/bin/chrome-devtools-mcp.js

Sources: CONTRIBUTING.md:40-43

VS Code SSH Configuration

When running the inspector with VS Code SSH, two ports are spawned:

Manual port forwarding may be required for port 6277.

Sources: CONTRIBUTING.md:54-58

Service Management

The CLI includes service management commands:

chrome-devtools start   # Start or restart chrome-devtools-mcp
chrome-devtools status  # Check if chrome-devtools-mcp is running
chrome-devtools stop    # Stop chrome-devtools-mcp if running

Sources: skills/chrome-devtools-cli/SKILL.md:67-70

For AI workflows, the background server starts implicitly on first tool call—do not manually run start/status/stop before each use.

CLI Arguments and Configuration

Configure the MCP server behavior using CLI arguments in your MCP configuration:

npx chrome-devtools-mcp@latest --help

Common Configuration Flags

Sources: skills/chrome-devtools-cli/SKILL.md:1-3

TypeScript Development Guidelines

When developing or contributing to this project, adhere to strict TypeScript rules:

Sources: AGENTS.md:13-20

Troubleshooting

Command Not Found

If chrome-devtools is not recognized after installation:

1. Ensure your global npm bin directory is in your system's PATH
2. Restart your terminal or source your shell configuration file (e.g., .bashrc, .zshrc)

Sources: skills/chrome-devtools-cli/references/installation.md:11-13

Permission Errors

If you encounter EACCES or permission errors during installation:

• Do not use sudo
• Use a node version manager like nvm
• Or configure npm to use a different global directory

Sources: skills/chrome-devtools-cli/references/installation.md:16-19

Old Version Running

If an outdated version is running:

chrome-devtools stop && npm uninstall -g chrome-devtools-mcp
npm i chrome-devtools-mcp@latest -g

Sources: skills/chrome-devtools-cli/references/installation.md:22-25

Debug Logging

To write debug logs to log.txt in the working directory, see the debugging section in CONTRIBUTING.md.

Sources: CONTRIBUTING.md:62-63

Lighthouse Dependency Updates

The project bundles Lighthouse for performance auditing. To update the Lighthouse dependency:

1. Update the Lighthouse version in package.json
2. Run npm install
3. Check out the corresponding Lighthouse repository revision to a sibling directory (../lighthouse)
4. Run npm run update-lighthouse (requires yarn)
5. Commit the bundle

Sources: CONTRIBUTING.md:24-29

Quick Reference

# Global CLI installation
npm i chrome-devtools-mcp@latest -g

# Verify installation
chrome-devtools status

# Development setup
git clone https://github.com/ChromeDevTools/chrome-devtools-mcp.git
cd chrome-devtools-mcp
nvm use
npm ci
npm run build
npm run test

# MCP server configuration
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "node",
      "args": ["/path-to/build/src/bin/chrome-devtools-mcp.js"]
    }
  }
}

Related Pages

Related topics: Installation and Setup, CLI Reference, MCP Protocol Integration

Configuration Reference

This page documents all configuration options available for the chrome-devtools-mcp project, covering CLI arguments, MCP server initialization, Puppeteer browser settings, and MCP client configuration files.

Overview

The chrome-devtools-mcp project supports multiple layers of configuration:

1. CLI Arguments - Command-line flags passed when starting the MCP server or CLI
2. Puppeteer Configuration - Browser launch and connection settings
3. MCP Client Configuration - JSON configuration for connecting MCP clients

Configuration flows through the application as follows:

graph TD
    A[CLI Arguments] --> B[chrome-devtools-mcp-cli-options.ts]
    B --> C[ParsedArguments Type]
    C --> D[chrome-devtools-mcp-main.ts]
    D --> E[Puppeteer Launch]
    F[.mcp.json] --> G[MCP Client]
    G --> H[MCP Server Connection]

CLI Configuration

The MCP server accepts numerous command-line arguments for customization. These are defined in src/bin/chrome-devtools-mcp-cli-options.ts and typed via the ParsedArguments interface.

General Options

Sources: src/bin/chrome-devtools-mcp-cli-options.ts

Browser Connection Options

Sources: src/bin/chrome-devtools-mcp-cli-options.ts

Browser Launch Options

Sources: src/bin/chrome-devtools-mcp-cli-options.ts

MCP Server Categories

The MCP server organizes tools into categories. Categories can be enabled or disabled using --category* flags:

# Enable extension support
chrome-devtools-mcp --categoryExtensions=true

# Enable experimental features
chrome-devtools-mcp --categoryExperimental=true --experimentalVision=true

Sources: src/tools/categories.ts Sources: skills/chrome-devtools/SKILL.md

Experimental Features

Experimental features require explicit enabling via CLI flags:

# Start with experimental vision mode
chrome-devtools-mcp --experimentalVision=true

Sources: skills/chrome-devtools-cli/SKILL.md

Debugging Options

# Run with debug logging to log.txt
npx @modelcontextprotocol/inspector node /build/src/bin/chrome-devtools-mcp.js --log-file=/path/to/log.txt

Sources: CONTRIBUTING.md

Puppeteer Configuration

The project uses Puppeteer for browser automation. Configuration is defined in puppeteer.config.cjs and can be overridden via CLI arguments.

Configuration File Structure

// puppeteer.config.cjs
module.exports = {
  puppeteer: {
    // Browser launch arguments
    args: [
      '--no-sandbox',
      '--disable-setuid-sandbox',
      '--disable-dev-shm-usage',
    ],
    // Default launch settings
    headless: true,
  }
};

Default Browser Arguments

The following Chromium arguments are passed by default:

Connection Modes

The MCP server supports two browser connection modes:

graph TD
    A[Start chrome-devtools-mcp] --> B{--browserUrl provided?}
    B -->|Yes| C[Remote Connection Mode]
    B -->|No| D[Launch Mode]
    D --> E{--userDataDir provided?}
    E -->|Yes| F[Use existing profile]
    E -->|No| G[Create temporary profile]
    C --> H[Connect via CDP WebSocket]
    F --> I[Puppeteer.launch]
    G --> I

1. Launch Mode (default): Puppeteer launches a new Chrome instance
2. Remote Connection Mode: Connect to an existing Chrome via --browserUrl

Sources: src/bin/chrome-devtools-mcp-main.ts

MCP Client Configuration

The .mcp.json file provides configuration for MCP clients connecting to the server.

Example Configuration

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

Extended Configuration Example

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "node",
      "args": [
        "/path/to/chrome-devtools-mcp/build/src/bin/chrome-devtools-mcp.js",
        "--port", "6274",
        "--headless", "false",
        "--categoryExtensions", "true"
      ],
      "env": {}
    }
  }
}

Configuration for Remote Connection

To connect to a specific Chrome instance:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--browserUrl", "http://localhost:9222",
        "--autoConnect", "true"
      ]
    }
  }
}

Sources: .mcp.json

Tool Categories and Annotations

Tools are annotated with metadata that affects their availability based on configuration:

Category Reference

Tool Annotation Schema

interface ToolAnnotation {
  title?: string;
  category?: ToolCategory;
  conditions?: string[];  // Required flags for tool availability
  readOnlyHint?: boolean; // Indicates if tool modifies browser state
}

Tools marked with readOnlyHint: false may be blocked in read-only MCP modes.

graph LR
    A[Tool Annotation] --> B[readOnlyHint]
    A --> C[category]
    A --> D[conditions]
    B --> E{Client Mode}
    C --> F[Category Filter]
    D --> G[Flag Check]
    E -->|Plan/ReadOnly| H[Only readOnlyHint=true]
    E -->|Normal| I[All tools]

Sources: src/tools/ToolDefinition.ts Sources: skills/troubleshooting/SKILL.md

Environment Variables

Configuration Precedence

Configuration values are resolved in the following order (highest to lowest):

1. CLI Arguments - Explicit flags passed at runtime
2. Environment Variables - Set in shell or .env files
3. Configuration Files - .mcp.json, puppeteer.config.cjs
4. Default Values - Built-in defaults in source code

graph TD
    A[Configuration Resolution] --> B[CLI Arguments]
    A --> C[Environment Variables]
    A --> D[Config Files]
    A --> E[Defaults]
    B --> F[Final Config]
    C --> F
    D --> F
    E --> F
    style B fill:#ff9999
    style F fill:#99ff99

Quick Reference

Minimal Configuration

# Default settings (headless, localhost:6274)
npx chrome-devtools-mcp@latest

Common Configurations

# Visible browser with extensions
chrome-devtools-mcp --headless=false --categoryExtensions=true

# Remote Chrome connection
chrome-devtools-mcp --browserUrl=http://localhost:9222

# Custom port
chrome-devtools-mcp --port=9000

Troubleshooting Configuration Issues

Sources: skills/troubleshooting/SKILL.md

Related Pages

Related topics: Project Overview, MCP Protocol Integration, Telemetry and Monitoring

System Architecture

Overview

The chrome-devtools-mcp project implements a Model Context Protocol (MCP) server that provides programmatic control over Chrome DevTools through a well-defined architecture of interconnected components. The system enables AI assistants and CLI tools to interact with a headless Chrome browser instance by exposing browser operations as typed tools with schema validation.

The architecture follows a layered design pattern with clear separation between the protocol layer (MCP), the tool definition system, browser management, and page-level interactions. This modular approach allows for extensibility while maintaining type safety and consistent behavior across all exposed functionality.

Sources: AGENTS.md

High-Level Architecture

graph TD
    subgraph "Client Layer"
        CLI[CLI Tool<br>chrome-devtools]
        AI[AI Assistant<br>MCP Client]
    end

    subgraph "MCP Protocol Layer"
        MCP[MCP Server<br>Protocol Handler]
        TDEF[Tool Definitions<br>Registry]
    end

    subgraph "Tool System"
        PAGES[Page Tools<br>Context-Aware]
        GLOB[Global Tools<br>Browser-Level]
    end

    subgraph "Browser Layer"
        CHROME[Chrome Browser<br>Puppeteer/CDP]
        PAGES_BROWSER[Pages<br>Target Management]
    end

    CLI --> MCP
    AI --> MCP
    MCP --> TDEF
    TDEF --> PAGES
    TDEF --> GLOB
    MCP --> CHROME
    CHROME --> PAGES_BROWSER

Core Components

1. Tool Definition System

The tool definition system is the foundation of the MCP server's extensibility. It provides factory functions for creating both page-scoped and global tools with automatic schema validation.

The defineTool function supports two invocation patterns:

// Direct tool definition
defineTool({
  name: 'tool_name',
  schema: { /* zod schema */ },
  handler: async (request, response, context) => { /* ... */ }
});

// Factory pattern with arguments
defineTool((args?: Args) => ({
  name: 'tool_name',
  schema: { /* zod schema using args */ },
  handler: async (request, response, context) => { /* ... */ }
}));

Sources: src/tools/ToolDefinition.ts:11-30

2. Page Scoped Tools

Page-scoped tools are tools that operate within the context of a specific browser page. They receive an additional page property in the request object and have access to the page's DOM, JavaScript context, and rendering state.

export function definePageTool<
  Schema extends zod.ZodRawShape,
  Args extends ParsedArguments = ParsedArguments,
>(
  definition:
    | PageToolDefinition<Schema>
    | ((args?: Args) => PageToolDefinition<Schema>),
): DefinedPageTool<Schema> | ((args?: Args) => DefinedPageTool<Schema>)

The returned tool automatically receives the pageScoped: true marker, which the MCP server uses to route requests appropriately. Each page-scoped tool handler receives:

• request: Contains both the parsed schema arguments and { page: ContextPage }
• response: Response object for sending results back to the client
• context: Full context object with browser and session information

Sources: src/tools/ToolDefinition.ts:52-90

3. Page Collector Pattern

The PageCollector class manages the lifecycle of browser pages and collects events/data from them. It implements the observer pattern for tracking page creation and destruction.

graph TD
    subgraph "PageCollector Lifecycle"
        INIT[init(pages: Page[])]
        ADD[addPage(page)]
        LISTEN[Start Event Listeners]
    end

    subgraph "Event Handling"
        CREATED[targetcreated<br>Event]
        DESTROYED[targetdestroyed<br>Event]
    end

    subgraph "Storage"
        STORAGE[(WeakMap&lt;Page,<br>Array&lt;Array&lt;WithSymbolId&lt;T&gt;&gt;&gt;&gt;)]
    end

    INIT --> ADD
    ADD --> LISTEN
    CREATED --> ADD
    LISTEN --> STORAGE

Key characteristics of the PageCollector:

Sources: src/PageCollector.ts

4. Browser Management

The browser module (src/browser.ts) handles the initialization and lifecycle of the Puppeteer-based Chrome browser instance. It provides the foundation for all page operations and CDP (Chrome DevTools Protocol) interactions.

The browser layer is responsible for:

• Launching headless Chrome with appropriate flags
• Managing browser context and isolated worlds
• Coordinating page creation and destruction
• Providing access to CDP sessions for advanced operations

Sources: src/browser.ts

5. WebMCP Tool System

The WebMCP system allows pages to expose their own tools to the MCP server, enabling dynamic tool discovery and execution from web applications.

graph LR
    WEB[Web Application<br>Exposes Tools]
    MCP[MCP Server]
    EXEC[execute_webmcp_tool]
    LIST[list_webmcp_tools]

    WEB --> LIST
    LIST --> WEB
    WEB --> EXEC
    EXEC --> WEB

Two primary tools manage WebMCP functionality:

export const listWebMcpTools = definePageTool({
  name: 'list_webmcp_tools',
  description: `Lists all WebMCP tools the page exposes.`,
  annotations: {
    category: ToolCategory.WEBMCP,
    readOnlyHint: true,
  },
  schema: {},
  blockedByDialog: false,
  handler: async (_request, response, _context) => {
    response.setListWebMcpTools();
  },
});

Sources: src/tools/webmcp.ts

Tool Categories

Tools are organized into categories for logical grouping and documentation purposes. The category system enables documentation generation and tool discovery.

Sources: src/tools/categories.ts

Request/Response Flow

sequenceDiagram
    participant Client
    participant MCP as MCP Server
    participant TDEF as Tool Definitions
    participant HANDLER as Tool Handler
    participant BROWSER as Browser/Page

    Client->>MCP: Tool Request (with args)
    MCP->>TDEF: Lookup Tool Definition
    TDEF-->>MCP: Schema + Handler Reference
    MCP->>MCP: Validate Arguments (Zod)
    MCP->>HANDLER: Invoke Handler(request, response, context)
    HANDLER->>BROWSER: CDP Commands / Puppeteer API
    BROWSER-->>HANDLER: Result
    HANDLER-->>MCP: Update Response
    MCP-->>Client: JSON-RPC Response

Tool Schema System

All tool parameters are validated using Zod schemas, ensuring type safety and providing automatic OpenAPI-style documentation.

// Schema definition example
schema: {
  toolName: zod.string().describe('The name of the WebMCP tool to execute'),
  input: zod
    .string()
    .optional()
    .describe('The JSON-stringified parameters to pass to the WebMCP tool'),
}

The schema system supports:

• Required/Optional detection: Automatically determines if fields are required based on Zod type
• Type transformations: Applied via .transform() for input normalization
• Descriptions: Extracted for documentation generation
• Enumerations: Validated against allowed values

Common schema utilities include:

Sources: src/tools/ToolDefinition.ts:95-107

Error Handling Patterns

The architecture defines specific error constants for expected failure conditions:

export const CLOSE_PAGE_ERROR =
  'The last open page cannot be closed. It is fine to keep it open.';

This error message indicates that the MCP server intentionally allows users to keep the final browser page open rather than forcing closure, which is a deliberate UX decision for browser automation workflows.

Type Safety Guarantees

The codebase enforces strict TypeScript practices to maintain type safety:

Sources: AGENTS.md

Build and Test Infrastructure

graph LR
    subgraph "Build Commands"
        BUILD[npm run build<br>tsc compilation]
        TEST[npm run test<br>Build + Run Tests]
        FORMAT[npm run format<br>Fix linting]
        GEN[npm run gen<br>Generate Docs]
    end

    subgraph "Output Artifacts"
        JS[JavaScript<br>/build/src]
        TYPES[Type Declarations<br>/build/src]
        DOCS[Markdown Docs<br>/skills/*]
    end

    BUILD --> JS
    BUILD --> TYPES
    TEST --> JS
    GEN --> DOCS

The project uses a standardized build pipeline that ensures type correctness at compile time and provides consistent tooling for development tasks.

Summary

The chrome-devtools-mcp system architecture provides:

1. Extensible Tool System: Factory functions for creating typed, validated tools
2. Page Context Awareness: Automatic injection of page context into tool handlers
3. Event-Driven Page Management: Observer pattern for tracking browser page lifecycle
4. Schema Validation: Zod-based runtime validation with compile-time type inference
5. WebMCP Integration: Bidirectional tool exposure between server and web pages
6. Strict Type Safety: No escape hatches for type checking, ensuring reliability

This architecture enables reliable browser automation while maintaining the flexibility needed for diverse use cases ranging from simple navigation to complex performance profiling and accessibility debugging.

Related Pages

Related topics: System Architecture, Input and Navigation Automation Tools, Debugging and Inspection Tools

MCP Protocol Integration

Overview

The chrome-devtools-mcp project implements a Model Context Protocol (MCP) server that enables AI assistants and MCP clients to interact with Chrome DevTools programmatically. This integration provides a standardized interface for browser automation, debugging, and performance analysis through a collection of well-defined tools.

The MCP protocol serves as the communication layer between AI assistants and the Chrome browser, allowing tools to be discovered, invoked, and executed remotely. The server handles tool registration, request routing, response formatting, and maintains state across multiple browser pages.

Sources: src/index.ts:1-50

Architecture

High-Level System Design

graph TD
    MCP_CLIENT["MCP Client / AI Assistant"]
    MCP_SERVER["MCP Server<br/>(chrome-devtools-mcp)"]
    TOOL_REGISTRY["Tool Registry"]
    BROWSER["Chrome Browser"]
    CDP["Chrome DevTools Protocol"]
    
    MCP_CLIENT -->|"Call Tool Request"| MCP_SERVER
    MCP_SERVER -->|"Tool Definitions"| MCP_CLIENT
    MCP_SERVER --> TOOL_REGISTRY
    TOOL_REGISTRY -->|"Handler Execution"| MCP_SERVER
    MCP_SERVER -->|"CDP Commands"| BROWSER
    BROWSER --> CDP

Tool Registration Flow

graph TD
    START["Server Initialization"] --> CREATE_TOOLS["createTools()"]
    CREATE_TOOLS --> REGISTER["registerTool()"]
    REGISTER --> DEFINE["definePageTool()"]
    DEFINE --> SCHEMA["Schema Validation"]
    SCHEMA --> HANDLER["Handler Mapping"]
    HANDLER --> READY["Tool Available"]
    
    STYLE REGISTER fill:#90EE90
    STYLE READY fill:#98FB98

The MCP server initializes by invoking createTools() which returns an array of tool definitions. Each tool is then registered with the MCP server using the protocol's setRequestHandler() method. Tools are defined using definePageTool() which establishes the tool name, description, input schema, annotations, and handler function.

Sources: src/index.ts:40-65

Tool Definition System

ToolDefinition.ts Pattern

Tools are defined using the definePageTool() function which creates a structured tool definition with type-safe schemas. The definition includes metadata, validation rules, and the execution handler.

export const listWebMcpTools = definePageTool({
  name: 'list_webmcp_tools',
  description: `Lists all WebMCP tools the page exposes.`,
  annotations: {
    category: ToolCategory.WEBMCP,
    readOnlyHint: true,
  },
  schema: {},
  blockedByDialog: false,
  handler: async (_request, response, _context) => {
    response.setListWebMcpTools();
  },
});

Sources: src/tools/webmcp.ts:15-27

Tool Definition Structure

Tool Annotations

The annotation system provides additional metadata about tools that MCP clients can use for tool selection, permission handling, and UI display.

interface ToolAnnotations {
  category?: ToolCategory;
  readOnlyHint?: boolean;
  conditions?: string[];
  // Additional annotation properties...
}

Sources: src/tools/ToolDefinition.ts

Tool Categories

Tools are organized into categories that help MCP clients understand their purpose and scope.

graph TD
    TOOLS["All Tools"]
    NAV["Navigation<br/>(navigate, new_page, close)"]
    INPUT["Input Automation<br/>(click, fill, type_text)"]
    EMULATE["Emulation<br/>(viewport, userAgent)"]
    PERFORMANCE["Performance<br/>(trace, analyze)"]
    NETWORK["Network<br/>(requests, cookies)"]
    WEBMCP["WebMCP<br/>(page-exposed tools)"]
    
    TOOLS --> NAV
    TOOLS --> INPUT
    TOOLS --> EMULATE
    TOOLS --> PERFORMANCE
    TOOLS --> NETWORK
    TOOLS --> WEBMCP

Available Categories

Sources: src/tools/categories.ts

Response System

McpResponse Architecture

The response system formats tool execution results into structured MCP responses that include both human-readable markdown and machine-parseable structured content.

graph LR
    REQUEST["Tool Request"] --> HANDLER["Tool Handler"]
    HANDLER --> RESPONSE["McpResponse"]
    RESPONSE -->|Text Content| MARKDOWN["Markdown Output"]
    RESPONSE -->|Structured Data| JSON["JSON / Structured"]
    
    subgraph Response Components
        TOOL_DEFS["Tool Definitions"]
        NETWORK["Network Requests"]
        PAGINATION["Pagination Info"]
        WEBMCP_TOOLS["WebMCP Tools"]
    end
    
    RESPONSE --> TOOL_DEFS
    RESPONSE --> NETWORK
    RESPONSE --> PAGINATION
    RESPONSE --> WEBMCP_TOOLS

Response Formatting Features

Sources: src/McpResponse.ts:50-120

Structured Content Model

The structuredContent object provides programmatic access to response data:

interface StructuredContent {
  webmcpTools?: WebMcpToolInfo[];
  networkRequests?: NetworkRequest[];
  pagination?: PaginationInfo;
  [key: string]: unknown;
}

Pagination Support

When handling large datasets (e.g., network requests), the response includes pagination metadata:

const paginationData = this.#dataWithPagination(
  requests,
  this.#networkRequestsOptions.pagination,
);
structuredContent.pagination = paginationData.pagination;

Sources: src/McpResponse.ts:150-180

WebMCP Integration

WebMCP enables web pages to expose custom tools that MCP clients can discover and invoke. This creates a two-way communication channel where the browser can extend its capabilities based on the loaded page.

graph TD
    MCP_CLIENT["MCP Client"]
    SERVER["MCP Server"]
    CHROME["Chrome Browser"]
    WEB_PAGE["Web Page"]
    
    subgraph Discovery Flow
        CLIENT_LIST["list_webmcp_tools"]
        SERVER -->|"Query"| CHROME
        CHROME --> WEB_PAGE
        WEB_PAGE -->|"Exposes tools"| CHROME
        CHROME -->|"Tool list"| SERVER
        SERVER -->|"Tool names"| CLIENT_LIST
    end
    
    subgraph Execution Flow
        EXEC["execute_webmcp_tool"]
        CLIENT -->|"toolName + input"| SERVER
        SERVER -->|"Forward"| CHROME
        CHROME --> WEB_PAGE
        WEB_PAGE -->|"Execute"| RESULT["Result"]
    end

WebMCP Tools

The execute_webmcp_tool accepts input as a JSON string which is parsed and passed to the page-exposed tool:

let input: Record<string, unknown> = {};
if (request.params.input) {
  try {
    const parsed = JSON.parse(request.params.input);
    if (typeof parsed === 'object' && parsed !== null) {
      input = parsed;
    }
  } catch (error) {
    // Handle parse error
  }
}

Sources: src/tools/webmcp.ts:29-60

Tool Documentation Generation

The repository includes a documentation generation system that parses tool definitions and produces formatted markdown:

graph TD
    SOURCE["Tool Source Files"]
    PARSER["Documentation Parser"]
    ANNOTATIONS["Parse Annotations"]
    SCHEMA["Parse Input Schema"]
    CROSSLINKS["Add Cross-References"]
    OUTPUT["Markdown Documentation"]
    
    SOURCE --> PARSER
    PARSER --> ANNOTATIONS
    PARSER --> SCHEMA
    ANNOTATIONS --> CROSSLINKS
    SCHEMA --> CROSSLINKS
    CROSSLINKS --> OUTPUT

Schema Documentation

Properties are sorted by required status first, then alphabetically:

const propertyNames = Object.keys(properties).sort((a, b) => {
  const aRequired = required.includes(a);
  const bRequired = required.includes(b);
  if (aRequired && !bRequired) return -1;
  if (!aRequired && bRequired) return 1;
  return a.localeCompare(b);
});

Required properties are marked with (required) and optional properties with _(optional)_.

Sources: scripts/generate-docs.ts:100-140

Server Initialization

Startup Sequence

sequenceDiagram
    participant CLI as CLI / MCP Client
    participant Server as MCP Server
    participant Tools as Tool Registry
    participant Browser as Chrome Browser
    
    CLI->>Server: Initialize with args
    Server->>Server: parseArguments()
    Server->>Tools: createTools()
    Tools->>Server: Tool definitions
    loop For each tool
        Server->>Server: registerTool()
    end
    Server->>Server: loadIssueDescriptions()
    Server->>CLI: Server ready

Tool Registration Implementation

const tools = createTools(serverArgs);
for (const tool of tools) {
  server.setRequestHandler(
    {name: tool.name, description: tool.description, ...},
    async (params) => {
      return await toolHandler.handle(params);
    },
  );
}

Sources: src/index.ts:45-60

Configuration and Flags

The MCP server accepts various configuration options that affect tool behavior:

Disclaimer System

The server logs disclaimers on startup to inform users about data exposure:

export const logDisclaimers = (args) => {
  console.error(`chrome-devtools-mcp exposes content of the browser instance...`);
  
  if (!args.slim && args.performanceCrux) {
    console.error(`Performance tools may send trace URLs to Google CrUX API...`);
  }
};

Sources: src/index.ts:70-90

Type Safety

The codebase enforces strict TypeScript practices:

Tools use Zod schemas for runtime validation, ensuring that the runtime behavior matches the TypeScript types:

schema: {
  toolName: zod.string().describe('The name of the WebMCP tool to execute'),
  input: zod.string().optional().describe('The JSON-stringified parameters...'),
},

Sources: src/tools/webmcp.ts:30-40

Related Pages

Related topics: Debugging and Inspection Tools, Performance Analysis Tools, Configuration Reference

Input and Navigation Automation Tools

Overview

The Input and Navigation Automation Tools constitute the core interaction layer of the chrome-devtools-mcp project, enabling programmatic control over browser pages through the Chrome DevTools Protocol (CDP). These tools allow AI agents and automated scripts to simulate real user interactions including keyboard input, mouse actions, page navigation, and environment emulation.

Sources: skills/chrome-devtools/SKILL.md

Architecture

The automation system is organized into three primary tool categories that work in concert to provide comprehensive browser control:

graph TD
    A[chrome-devtools-mcp Tools] --> B[Input Tools]
    A --> C[Navigation Tools]
    A --> D[Emulation Tools]
    
    B --> B1[click]
    B --> B2[fill]
    B --> B3[type_text]
    B --> B4[press_key]
    B --> B5[hover]
    B --> B6[drag]
    B --> B7[upload_file]
    
    C --> C1[navigate_page]
    C --> C2[new_page]
    C --> C3[select_page]
    C --> C4[close_page]
    C --> C5[list_pages]
    
    D --> D1[emulate]
    D --> D2[resize_page]
    
    E[WaitForHelper] --> B
    E --> C

Sources: src/tools/ToolDefinition.ts

Input Tools

Input tools provide the capability to simulate user interactions with page elements. All input operations require a valid element uid obtained from a previous take_snapshot call.

Sources: skills/chrome-devtools-cli/SKILL.md

Core Input Operations

Sources: src/tools/input.ts

Keyboard Handling

The keyboard system supports complex key combinations through a modifier parsing mechanism defined in src/utils/keyboard.ts:

// Key format: "Control+A", "Control+Shift+R", "Alt+F4"
const tokens = parseKey(request.params.key);
const [key, ...modifiers] = tokens;

Sources: src/utils/keyboard.ts

Supported modifiers:

• Control
• Shift
• Alt
• Meta

Interaction Workflow

sequenceDiagram
    participant Agent as AI Agent
    participant Snapshot as take_snapshot
    participant Input as Input Tool
    participant Page as Chrome Page
    
    Agent->>Page: navigate_page / new_page
    Agent->>Snapshot: take_snapshot
    Snapshot-->>Agent: Element UIDs
    Agent->>Input: click uid="1_5"
    Input->>Page: CDP Input.dispatchMouseEvent
    Page-->>Input: Mouse click confirmed
    Input-->>Agent: Result response

Sources: skills/chrome-devtools/SKILL.md

Common Input Patterns

Typing with Submit:

chrome-devtools type_text "hello" --submitKey "Enter"

Click with Snapshot:

chrome-devtools click "uid" --includeSnapshot true

Pressing Key Combinations:

chrome-devtools press_key "Control+A" --includeSnapshot true

Sources: skills/chrome-devtools-cli/SKILL.md

Navigation Tools

Navigation tools manage page lifecycle and context within the browser instance.

Sources: src/tools/pages.ts

Page Management Operations

Sources: src/tools/pages.ts

Navigation Types

The navigate_page tool supports multiple navigation types:

type: "navigate" | "reload" | "back" | "forward"

Sources: src/tools/pages.ts

Before Unload Handling

When navigating away from a page with pending changes, the browser may display a "before unload" dialog:

chrome-devtools navigate_page --url "https://example.com" --handleBeforeUnload "accept"

Sources: skills/chrome-devtools-cli/SKILL.md

Multi-Page Context Management

Pages are managed with a zero-based index system. The select_page tool changes the active page context for subsequent tool calls:

# List pages to see available pages
chrome-devtools list_pages

# Select page by index
chrome-devtools select_page 1 --bringToFront true

Sources: skills/chrome-devtools/SKILL.md

Isolated Contexts

New pages can be created with isolated JavaScript contexts, useful for testing extensions or isolated scripts:

chrome-devtools new_page "https://example.com" --isolatedContext "ctx"

Sources: src/tools/pages.ts

Page Lifecycle

stateDiagram-v2
    [*] --> created: new_page
    created --> active: select_page
    active --> background: select_page (other)
    background --> active: select_page (bringToFront)
    active --> closed: close_page
    closed --> [*]
    
    active --> navigating: navigate_page
    navigating --> active: Load complete

Sources: src/PageCollector.ts

Emulation Tools

Emulation tools control browser environment settings including network conditions, CPU throttling, geolocation, viewport, and user agent.

Sources: src/tools/emulation.ts

Emulation Capabilities

Sources: src/tools/emulation.ts

Emulation Commands

Network Emulation:

chrome-devtools emulate --networkConditions "Offline"

Multiple Emulations:

chrome-devtools emulate --cpuThrottlingRate 4 --geolocation "0x0"

Visual Emulation:

chrome-devtools emulate --colorScheme "dark" --viewport "1920x1080"

User Agent Spoofing:

chrome-devtools emulate --userAgent "Mozilla/5.0..."

Sources: skills/chrome-devtools-cli/SKILL.md

Page Resize

The resize_page tool resizes the selected page's window:

chrome-devtools resize_page 1920 1080

Sources: src/tools/emulation.ts

WaitForHelper

The WaitForHelper module provides synchronization mechanisms to ensure page elements are ready before interactions occur.

Sources: src/WaitForHelper.ts

Wait Strategies

Sources: skills/chrome-devtools/SKILL.md

Recommended Workflow

The official workflow ensures reliable automation:

1. Navigate: Use navigate_page or new_page
2. Wait: Use wait_for if you know what to look for
3. Snapshot: Use take_snapshot to understand page structure
4. Interact: Use element uids from snapshot for click, fill, etc.

Sources: skills/chrome-devtools/SKILL.md

Tool Configuration Schema

All tools follow a consistent schema pattern defined in src/tools/ToolDefinition.ts:

export const timeoutSchema = {
  timeout: zod
    .number()
    .int()
    .optional()
    .describe(
      `Maximum wait time in milliseconds. If set to 0, the default timeout will be used.`,
    )
    .transform(value => {
      return value && value <= 0 ? undefined : value;
    }),
};

export const pageIdSchema = {
  pageId: zod.number().optional().describe('Targets a specific page by ID.'),
};

Sources: src/tools/ToolDefinition.ts

IncludeSnapshot Pattern

Many input tools support the includeSnapshot flag to return an updated page snapshot after the action:

chrome-devtools click "id" --includeSnapshot true

When true, the response includes the full accessibility tree, allowing chaining without an explicit take_snapshot call.

Sources: skills/chrome-devtools-cli/SKILL.md

Error Handling

Dialog Blocking

Some input tools are blocked when a dialog is present:

blockedByDialog: true,

In such cases, use handle_dialog first:

chrome-devtools handle_dialog accept
chrome-devtools handle_dialog dismiss --promptText "hi"

Sources: src/tools/input.ts

Page Closure Restrictions

The last open page cannot be closed:

export const CLOSE_PAGE_ERROR =
  'The last open page cannot be closed. It is fine to keep it open.';

Sources: src/tools/ToolDefinition.ts

CLI Usage

All tools are accessible via the chrome-devtools CLI:

chrome-devtools <tool> [arguments] [flags]

Help System

chrome-devtools take_snapshot --help

Output Formats

By default, output is in Markdown. Use --output-format=json for JSON output:

chrome-devtools list_pages --output-format=json

Sources: skills/chrome-devtools-cli/SKILL.md

Tool Categories

Tools are organized into categories for documentation and navigation:

Sources: docs/tool-reference.md

Testing and Validation

The repository includes test scenarios that validate tool behavior:

expectations: calls => {
  assert.ok(
    calls[0].name === 'navigate_page' || calls[0].name === 'new_page',
  );
  assert.strictEqual(calls[1].name, 'take_snapshot');
  assert.strictEqual(calls[2].name, 'fill_form');
}

Sources: scripts/eval_scenarios/fill_select_and_checkboxes_test.ts

Summary

The Input and Navigation Automation Tools provide a comprehensive API for browser automation through:

• Input Tools: Simulate user interactions with precise element targeting
• Navigation Tools: Full page lifecycle management including multi-page contexts
• Emulation Tools: Control browser environment for testing various conditions
• WaitForHelper: Synchronization primitives for reliable automation

These tools work together to enable reliable browser automation workflows suitable for testing, scraping, and AI agent interactions.

Related Pages

Related topics: Input and Navigation Automation Tools, Performance Analysis Tools

Debugging and Inspection Tools

Overview

The Debugging and Inspection Tools in chrome-devtools-mcp provide comprehensive capabilities for examining browser page state, accessibility trees, console output, network activity, and memory usage. These tools serve as the primary interface for automated debugging, accessibility auditing, and performance analysis workflows.

The inspection layer is built on Chrome DevTools Protocol (CDP) and exposes both programmatic and visual inspection capabilities through a unified MCP (Model Context Protocol) interface. All tools operate on the currently selected page context, enabling sequential inspection workflows.

Architecture

graph TD
    subgraph "Inspection Layer"
        SNAP[Snapshot Tools]
        SCR[Screen Tools]
        NET[Network Tools]
        CON[Console Tools]
        MEM[Memory Tools]
    end
    
    subgraph "Formatting Layer"
        SF[SnapshotFormatter]
        NF[NetworkFormatter]
        CF[ConsoleFormatter]
    end
    
    subgraph "CDP Integration"
        CDP[Chrome DevTools Protocol]
        PUP[CDP Puppeteer Bridge]
    end
    
    SNAP --> SF
    SCR --> CDP
    NET --> NF
    CON --> CF
    MEM --> CDP
    
    SF --> PUP
    NF --> PUP
    CF --> PUP
    PUP --> CDP
    
    style SNAP fill:#e1f5fe
    style SCR fill:#e1f5fe
    style NET fill:#e1f5fe
    style CON fill:#e1f5fe
    style MEM fill:#e1f5fe

Page Snapshot Tools

take_snapshot

The primary inspection tool that captures the accessibility tree of the currently selected page. The snapshot provides a text-based representation of page structure with unique element identifiers (UIDs) used for subsequent interaction.

Parameters:

Key Features:

• Returns element hierarchy with unique uid identifiers
• Indicates which element is selected in DevTools Elements panel
• Supports output to file for large snapshots
• Based on accessibility tree, not raw DOM (reflects what assistive technologies perceive)
• Marked as blockedByDialog: true to handle browser dialogs gracefully

Source: src/tools/snapshot.ts:17-43

wait_for

Suspends execution until a specified condition is met on the page, enabling synchronization with dynamic content loading.

Source: src/tools/snapshot.ts:45+

Console Tools

list_console_messages

Retrieves console output and browser-issued accessibility audits from the current page. This tool captures both developer-initiated logs and automatic Chrome accessibility checks.

Use Cases:

• Capturing console.log, console.error, and other console methods
• Detecting browser-issued accessibility issues
• Preserving messages from page load that occurred before inspection
• Filtering by message types (log, warn, error, info, debug, issue)

Source: src/tools/console.ts

Console Output Types

The console formatter (ConsoleFormatter.ts) processes raw CDP messages into structured, human-readable output with proper formatting of objects and arrays.

Source: src/formatters/ConsoleFormatter.ts

Network Inspection Tools

Network Monitoring

The network inspection subsystem captures HTTP traffic, WebSocket communications, and resource loading timing. Network tools are essential for debugging API calls, identifying slow resources, and analyzing request/response patterns.

Source: src/tools/network.ts

Network Formatter: src/formatters/NetworkFormatter.ts

Network Parameters

Memory Inspection Tools

take_memory_snapshot

Captures V8 heap memory snapshots for debugging memory leaks and analyzing memory consumption patterns. Heap snapshots are saved in Chrome's standard .heapsnapshot format.

Parameters:

Use Cases:

• Identifying memory leaks
• Analyzing object retention paths
• Comparing heap states before/after operations
• Finding detached DOM trees

Source: src/tools/memory.ts

Screenshot Tools

take_screenshot

Captures visual representation of the current page state. Unlike snapshots, screenshots provide pixel-level fidelity for visual inspection when accessibility tree information is insufficient.

Use Cases:

• Visual debugging when structure is unclear
• Capturing rendered UI state
• Documenting bug reproductions
• Inspecting CSS-dependent layouts

Source: src/tools/screenshot.ts

Snapshot Formatting

The SnapshotFormatter (SnapshotFormatter.ts) transforms raw accessibility tree data into human-readable hierarchical text format.

Output Structure:

uid=1_0 RootWebArea "Example Domain" url="https://example.com/"
  uid=1_1 heading "Example Domain" level="1"
  uid=1_2 paragraph "Some content text"

Key Formatting Features:

• Hierarchical indentation reflecting DOM tree structure
• UID assignment following CDP node IDs
• Role-based element classification (heading, paragraph, button, etc.)
• Attribute inclusion for semantic details
• ARIA property preservation

Source: src/formatters/SnapshotFormatter.ts

Workflow Patterns

Standard Inspection Workflow

graph LR
    A[Navigate to Page] --> B[wait_for Condition]
    B --> C[take_snapshot]
    C --> D{Issue Found?}
    D -->|Yes| E[Take Screenshot]
    E --> F[Check Console Logs]
    F --> G[Document Findings]
    D -->|No| H[Continue Testing]
    
    style A fill:#c8e6c9
    style C fill:#bbdefb
    style F fill:#fff9c4

Accessibility Audit Workflow

1. Lighthouse Audit: Run comprehensive accessibility audit via MCP tools
2. Console Inspection: Check for browser-issued issue type messages
3. Snapshot Analysis: Verify heading hierarchy, ARIA labels, semantic landmarks
4. Form Input Verification: Ensure all inputs have associated labels
5. Focus Navigation: Test keyboard navigation with press_key tool

Source: skills/a11y-debugging/SKILL.md

Tool Categories

All inspection tools are categorized under ToolCategory.DEBUGGING for organizational purposes and MCP tool discovery.

Source: src/tools/snapshot.ts:10

Category Matrix

*Note: take_snapshot is not read-only due to the filePath parameter allowing file system writes.

Integration with Input Automation

Inspection tools work in conjunction with input automation tools to enable test-verify workflows:

graph TD
    INSPECT[Inspection Tools] <-->|UID feedback| INTERACT[Input Automation]
    
    INSPECT --> SNAP[Snapshot with UIDs]
    INTERACT --> CLICK[click uid]
    INTERACT --> FILL[fill uid "text"]
    INTERACT --> HOVER[hover uid]
    
    SNAP --> ELEM[Element UIDs]
    ELEM --> CLICK
    ELEM --> FILL
    ELEM --> HOVER

Source: skills/chrome-devtools/SKILL.md

Best Practices

1. Prefer Snapshots over Screenshots: Text snapshots are faster, machine-parseable, and more reliable for automation
2. Use File Output for Large Data: Specify filePath parameter when capturing large snapshots or traces
3. Wait Before Inspecting: Always use wait_for when content loads dynamically
4. Check Console First: Browser-issued issues often reveal accessibility problems without manual investigation
5. Keep Snapshots Current: Element UIDs may change after page mutations—take fresh snapshots before interactions

Output Formats

All inspection tools support multiple output formats via the --output-format flag:

Source: skills/chrome-devtools-cli/SKILL.md

Error Handling

Inspection tools handle common failure scenarios:

• Dialog Blocking: Tools with blockedByDialog: true will wait if a browser dialog appears
• Page Context Missing: Operations fail gracefully if no page is selected
• Path Validation: File operations validate paths before writing
• Timeout Handling: Configurable timeouts prevent indefinite waits

Source: src/tools/snapshot.ts:28-31

Related Pages

Related topics: Debugging and Inspection Tools, Telemetry and Monitoring

Performance Analysis Tools

The chrome-devtools-mcp repository provides a comprehensive suite of performance analysis tools through the Chrome DevTools Protocol integration. These tools enable automated performance auditing, runtime tracing, memory profiling, and network condition emulation.

Overview

Performance Analysis Tools in chrome-devtools-mcp encompass four primary domains:

Sources: src/tools/lighthouse.ts:1-20

Architecture

The performance analysis system follows a layered architecture:

graph TD
    subgraph "CLI Layer"
        CLI[CLI Commands<br/>chrome-devtools CLI]
    end
    
    subgraph "Tool Layer"
        LH[Lighthouse Audit Tool]
        PT[Performance Trace Tools]
        MS[Memory Snapshot Tools]
    end
    
    subgraph "Protocol Layer"
        CDP[Chrome DevTools Protocol]
    end
    
    subgraph "Processing Layer"
        HSP[Heap Snapshot Parser]
        TRP[Trace Event Parser]
        FMT[Result Formatters]
    end
    
    subgraph "Output Layer"
        JSON[JSON Reports]
        HTML[HTML Reports]
        SNAP[Heap Snapshots]
    end
    
    CLI --> LH
    CLI --> PT
    CLI --> MS
    
    LH --> CDP
    PT --> CDP
    MS --> CDP
    
    MS --> HSP
    PT --> TRP
    
    HSP --> FMT
    TRP --> FMT
    
    FMT --> JSON
    FMT --> HTML
    HSP --> SNAP

Lighthouse Audit Tool

The lighthouse_audit tool provides automated accessibility, SEO, and best practices auditing.

Tool Definition

export const lighthouseAudit = definePageTool({
  name: 'lighthouse_audit',
  description: `Get Lighthouse score and reports for accessibility, SEO, best practices, and agentic browsing. This excludes performance.`,
  schema: {
    mode: zod.enum(['navigation', 'snapshot']).default('navigation'),
    device: zod.enum(['desktop', 'mobile']).default('desktop'),
    outputDirPath: zod.string().optional(),
  },
});

Sources: src/tools/lighthouse.ts:19-40

Audit Categories

Parameters

Usage Workflow

graph LR
    A[Start Audit] --> B{Mode?}
    B -->|navigation| C[Reload Page]
    B -->|snapshot| D[Analyze Current State]
    C --> E[Run Lighthouse]
    D --> E
    E --> F[Generate JSON Report]
    F --> G[Parse Results]
    G --> H[Return Scores & Failed Audits]

Sources: src/tools/lighthouse.ts:40-60

Performance Tracing

The performance tracing system captures Chrome DevTools performance data for deep analysis.

Available Tools

Trace Configuration

LCP Analysis

The trace system integrates with LCP (Largest Contentful Paint) debugging:

async () => {
  return await new Promise(resolve => {
    new PerformanceObserver(list => {
      const entries = list.getEntries();
      const last = entries[entries.length - 1];
      resolve({
        element: last.element?.tagName,
        id: last.element?.id,
        className: last.element?.className,
        url: last.url,
        startTime: last.startTime,
        renderTime: last.renderTime,
        loadTime: last.loadTime,
        size: last.size,
      });
    }).observe({type: 'largest-contentful-paint', buffered: true});
  });
};

Sources: skills/debug-optimize-lcp/references/lcp-snippets.md:1-30

LCP Subpart Breakdown

LCP is measured across four subparts that sum to 100%:

Sources: skills/debug-optimize-lcp/SKILL.md:1-50

Memory Profiling

The memory profiling system captures and analyzes JavaScript heap snapshots.

Heap Snapshot Manager

The HeapSnapshotManager class handles snapshot lifecycle:

export class PageCollector<T> {
  #browser: Browser;
  protected storage = new WeakMap<Page, Array<Array<WithSymbolId<T>>>>();
  protected maxNavigationSaved = 3;
  
  async init(pages: Page[]) {
    for (const page of pages) {
      this.addPage(page);
    }
  }
}

Sources: src/PageCollector.ts:1-50

Snapshot Operations

Heap Snapshot Data Structure

The system processes snapshots with the following structure:

Sources: src/formatters/HeapSnapshotFormatter.ts:1-30

Trace Processing

The trace processing module parses Chrome DevTools trace events.

Parser Functions

interface ParsedTraceEvent {
  name: string;
  cat: string;
  ph: string;
  ts: number;
  dur?: number;
  args?: Record<string, unknown>;
}

Sources: src/trace-processing/parse.ts:1-20

Supported Event Types

Trace File Format

Trace files can be saved in two formats:

CLI Commands

The performance tools are accessible via the chrome-devtools CLI:

Performance Commands

# Start tracing with optional reload
chrome-devtools performance_start_trace true false

# Start trace and save to file
chrome-devtools performance_start_trace true true --filePath trace.gz

# Stop trace and optionally save
chrome-devtools performance_stop_trace
chrome-devtools performance_stop_trace --filePath "t.json"

# Analyze Performance Insights
chrome-devtools performance_analyze_insight "1" "LCPBreakdown"

Sources: skills/chrome-devtools-cli/SKILL.md:1-100

Memory Commands

# Capture heap snapshot
chrome-devtools take_memory_snapshot "./snap.heapsnapshot"

Emulation Commands

For realistic performance testing under constrained conditions:

# Network throttling
chrome-devtools emulate --networkConditions "Fast 3G"

# CPU throttling
chrome-devtools emulate --cpuThrottlingRate 4

# Combined emulation
chrome-devtools emulate --networkConditions "Slow 3G" --cpuThrottlingRate 4

Sources: skills/chrome-devtools-cli/SKILL.md:80-120

Common Performance Issues

LCP Issues Checklist

Sources: skills/debug-optimize-lcp/references/optimization-strategies.md:1-50

JavaScript Snippet for Issue Detection

() => {
  const issues = [];

  // Check for lazy-loaded images in viewport
  document.querySelectorAll('img[loading="lazy"]').forEach(img => {
    const rect = img.getBoundingClientRect();
    if (rect.top < window.innerHeight) {
      issues.push({
        issue: 'lazy-loaded image in viewport',
        element: img.outerHTML.substring(0, 200),
        fix: 'Remove loading="lazy" from this image'
      });
    }
  });

  return issues;
};

Sources: skills/debug-optimize-lcp/references/lcp-snippets.md:35-55

Test Scenarios

The repository includes test scenarios for performance tools:

export const scenario: TestScenario = {
  prompt: 'Check the performance of https://developers.chrome.com',
  maxTurns: 2,
  expectations: calls => {
    assert.strictEqual(calls.length, 2);
    assert.ok(
      calls[0].name === 'navigate_page' || calls[0].name === 'new_page',
    );
    assert.ok(calls[1].name === 'performance_start_trace');
  },
};

Sources: scripts/eval_scenarios/performance_test.ts:1-25

Related Documentation

• Lighthouse Documentation
• Chrome DevTools Performance Panel
• Memory Profiling
• LCP Web.dev Guide

Related Pages

Related topics: Configuration Reference, Installation and Setup, System Architecture

CLI Reference

The chrome-devtools-mcp CLI provides a command-line interface for interacting with Chrome DevTools, enabling browser automation, page manipulation, performance analysis, and network inspection directly from the terminal.

Overview

The CLI is built on top of the Model Context Protocol (MCP) and serves as the primary interface for users who prefer terminal-based workflows over programmatic SDK integration. It wraps the MCP server functionality into a user-friendly command structure.

graph TD
    A[User Terminal] -->|chrome-devtools command| B[CLI Entry Point]
    B --> C[chrome-devtools-cli-options.ts]
    C --> D[Argument Parsing]
    D --> E[chrome-devtools-mcp Server]
    E --> F[Chrome Browser Instance]
    F --> G[Page Context]
    G --> H[Tool Execution]
    H --> I[Response Output]

Sources: skills/chrome-devtools-cli/SKILL.md

Command Structure

The general command syntax follows:

chrome-devtools <tool> [arguments] [flags]

Global Flags

Sources: skills/chrome-devtools-cli/SKILL.md

Service Management Commands

These commands control the lifecycle of the chrome-devtools-mcp server.

chrome-devtools start   # Start or restart chrome-devtools-mcp
chrome-devtools status  # Check if chrome-devtools-mcp is running
chrome-devtools stop    # Stop chrome-devtools-mcp if any

The background server starts implicitly on first tool call. Users should not run start/status/stop before each use.

Sources: skills/chrome-devtools-cli/SKILL.md

Navigation Commands

Page Navigation

Page Management

Sources: skills/chrome-devtools-cli/SKILL.md

Input Automation Commands

These commands interact with elements identified by uid from snapshot operations.

Element Interaction

Keyboard and Text Input

File Upload

Dialog Handling

Sources: skills/chrome-devtools-cli/SKILL.md

Emulation Commands

Network Conditions

chrome-devtools emulate --networkConditions "Offline"

Performance Emulation

chrome-devtools emulate --cpuThrottlingRate 4 --geolocation "0x0"

Visual Emulation

chrome-devtools emulate --colorScheme "dark" --viewport "1920x1080"
chrome-devtools emulate --userAgent "Mozilla/5.0..."
chrome-devtools resize_page 1920 1080

Sources: skills/chrome-devtools-cli/SKILL.md

Performance Commands

Tracing

Analysis

Sources: skills/chrome-devtools-cli/SKILL.md

Extension Management Commands

Sources: skills/chrome-devtools-cli/SKILL.md

Experimental Features

Experimental tools require specific flags during server startup:

--experimentalVision=true   # Enable coordinate-based clicking
--experimentalScreencast=true # Enable screencast (requires ffmpeg)
--categoryExperimentalWebmcp=true # Enable WebMCP tools

Experimental Commands

Sources: skills/chrome-devtools-cli/SKILL.md

WebMCP Tools

WebMCP tools are exposed by the page itself and allow pages to define custom tools that the CLI can invoke.

chrome-devtools list_webmcp_tools    # List all WebMCP tools the page exposes
chrome-devtools execute_webmcp_tool "toolName" --input '{"key": "value"}'

Sources: src/tools/webmcp.ts

Tool Categories

The CLI tools are organized into categories that can be enabled or disabled:

Categories can be enabled via CLI flags:

chrome-devtools --categoryExtensions=true <tool>

Sources: skills/chrome-devtools/SKILL.md

Snapshot Format

The take_snapshot command returns a hierarchical tree structure:

uid=1_0 RootWebArea "Example Domain" url="https://example.com/"
  uid=1_1 heading "Example Domain" level="1"
  uid=1_2 link "Learn more" href="https://example.com/about"

Each element has a unique uid for interaction. The format shows:

• Element type (RootWebArea, heading, link, etc.)
• Text content
• Attributes (level, href, url)
• Unique identifier (uid) for command targeting

Sources: skills/chrome-devtools-cli/SKILL.md

Workflow Patterns

graph LR
    A[navigate_page] --> B[wait_for]
    B --> C[take_snapshot]
    C --> D{Get uid}
    D --> E[Interact with element]
    E --> F[click/fill/hover]
    F --> G[includeSnapshot?]
    G -->|Yes| C
    G -->|No| H[Continue]

Before Interacting with a Page

1. Navigate: Use navigate_page or new_page
2. Wait: Use wait_for to ensure content is loaded
3. Snapshot: Use take_snapshot to understand page structure
4. Interact: Use element uids from snapshot for commands

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

Sources: skills/chrome-devtools/SKILL.md

Slim Mode

The --slim mode provides a minimal set of tools focused on core navigation and interaction, without additional features like performance tracing or extensions.

Available slim tools include essential navigation and element interaction commands.

Sources: docs/slim-tool-reference.md

CLI Options Configuration

The CLI accepts the following configuration options (from src/bin/chrome-devtools-cli-options.ts):

Sources: src/bin/chrome-devtools-cli-options.ts

MCP Server Integration

sequenceDiagram
    participant User
    participant CLI
    participant MCPServer
    participant Chrome
    
    User->>CLI: chrome-devtools navigate_page
    CLI->>MCPServer: Tool Request
    MCPServer->>Chrome: CDP Command
    Chrome-->>MCPServer: CDP Response
    MCPServer-->>CLI: Tool Response
    CLI-->>User: Formatted Output

The CLI communicates with the MCP server using the Model Context Protocol over stdio transport. The server spawns Chrome as a child process and manages CDP (Chrome DevTools Protocol) connections.

Sources: scripts/generate-cli.ts

Installation

npm i chrome-devtools-mcp@latest -g
chrome-devtools status  # Verify installation

Troubleshooting

Sources: skills/chrome-devtools-cli/references/installation.md

Development Scripts

From package.json:

Sources: AGENTS.md

TypeScript Rules

The codebase follows strict TypeScript guidelines:

• No any type
• No as keyword for type casting
• No ! operator for type assertion
• No // @ts-ignore comments
• Prefer for..of over forEach

Sources: AGENTS.md

Related Pages

Related topics: System Architecture, Configuration Reference

Telemetry and Monitoring

Overview

The chrome-devtools-mcp project implements a telemetry and monitoring system located in the src/telemetry/ directory. This system is responsible for collecting, logging, and persisting usage metrics and error data from the MCP server operations.

System Architecture

The telemetry system comprises several interconnected components that work together to capture and report server behavior:

graph TD
    A[Tool Execution] --> B[Metrics Registry]
    A --> C[Clearcut Logger]
    B --> D[Persistence Layer]
    C --> D
    D --> E[Metrics Export]
    F[Watchdog Client] --> C
    G[Errors Module] --> C

Core Components

1. Metrics Registry (`metricsRegistry.ts`)

The metrics registry tracks tool call statistics and flag usage across the MCP server. It maintains counters and aggregations for:

• Tool invocation counts
• Flag usage patterns
• Performance-related metrics

The registry is populated by data defined in tool_call_metrics.json and flag_usage_metrics.json, which define the specific metrics to be tracked.

Sources: src/telemetry/metricsRegistry.ts

2. Clearcut Logger (`ClearcutLogger.ts`)

ClearcutLogger is the primary logging mechanism for telemetry data. It handles:

• Structured logging of events
• Connection to telemetry backends
• Batch processing of log entries

Sources: src/telemetry/ClearcutLogger.ts

3. Watchdog Client (`WatchdogClient.ts`)

The WatchdogClient provides health monitoring functionality for the MCP server. It:

• Monitors server responsiveness
• Tracks resource utilization
• Reports health status to external monitoring systems

Sources: src/telemetry/WatchdogClient.ts

4. Errors Module (`errors.ts`)

The errors module handles error telemetry and reporting:

• Captures error conditions during tool execution
• Categorizes errors by type and severity
• Provides structured error data for logging

Sources: src/telemetry/errors.ts

5. Persistence Layer (`persistence.ts`)

The persistence module manages storage of telemetry data:

• Buffers metrics before transmission
• Handles local caching of data
• Manages data retention policies

Sources: src/telemetry/persistence.ts

6. Types (`types.ts`)

Central type definitions for all telemetry components including:

• Metric data structures
• Log entry formats
• Configuration interfaces

Sources: src/telemetry/types.ts

Metrics Configuration

Tool Call Metrics (`tool_call_metrics.json`)

This JSON file defines which tools should have their invocations tracked. The format includes tool names and associated metadata for metrics collection.

Sources: src/telemetry/tool_call_metrics.json

Flag Usage Metrics (`flag_usage_metrics.json`)

This configuration file tracks usage patterns of command-line flags and configuration options passed to the MCP server.

Sources: src/telemetry/flag_usage_metrics.json

Data Flow

sequenceDiagram
    participant User as User/Tool
    participant Registry as Metrics Registry
    participant Logger as Clearcut Logger
    participant Persistence as Persistence Layer
    participant Backend as Telemetry Backend

    User->>Registry: Record metric
    Registry->>Persistence: Buffer data
    User->>Logger: Log event
    Logger->>Persistence: Batch events
    Persistence->>Backend: Flush data
    Backend-->>Persistence: Acknowledge

Integration with Tool System

The telemetry system integrates with the tool definition infrastructure defined in ToolDefinition.ts. Tool execution flows through the telemetry system enabling automatic metrics collection.

Sources: src/tools/ToolDefinition.ts:1-75

WaitForHelper Integration

The WaitForHelper class handles navigation and event timing which feeds into performance telemetry. It tracks navigation events and DOM stability which are essential for understanding tool execution performance.

Sources: src/WaitForHelper.ts:1-60

PageCollector Event Monitoring

The PageCollector class monitors page lifecycle events that contribute to telemetry data:

• Target creation/destruction events
• Navigation events
• Resource loading patterns

Sources: src/PageCollector.ts:1-60

Debug Logging

For troubleshooting telemetry issues, the project supports debug logging via the DEBUG environment variable. To write debug logs to a file:

npx @modelcontextprotocol/inspector node /build/src/bin/chrome-devtools-mcp.js --log-file=/your/desired/path/log.txt

Sources: CONTRIBUTING.md

Configuration Options

Best Practices

1. Review metrics before adding new ones - Ensure the metric provides meaningful insight
2. Use structured logging - Prefer the ClearcutLogger for consistency
3. Handle telemetry failures gracefully - Telemetry should not block tool execution
4. Test metrics collection - Verify metrics are recorded correctly in test scenarios

Sources: CONTRIBUTING.md

Related Documentation

• AGENTS.md - General project instructions
• CONTRIBUTING.md - Debugging and development guide
• skills/chrome-devtools/SKILL.md - Tool usage patterns

Doramagic Pitfall Log

Doramagic extracted 16 source-linked risk signals. Review them before installing or handing real data to the project.

1. Configuration risk: performance_start_trace records 'CPU throttling: none / Network throttling: none' despite emulate setting throttling —…

• Severity: high
• Finding: Configuration risk is backed by a source signal: performance_start_trace records 'CPU throttling: none / Network throttling: none' despite emulate setting throttling —…. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1955

2. Installation risk: Auto-connect doesn't work on WSL with mirrored networking (Chrome on Windows host)

• Severity: medium
• Finding: Installation risk is backed by a source signal: Auto-connect doesn't work on WSL with mirrored networking (Chrome on Windows host). Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2004

3. Installation risk: Update check hardcodes registry.npmjs.org, ignoring user's npm registry configuration

• Severity: medium
• Finding: Installation risk is backed by a source signal: Update check hardcodes registry.npmjs.org, ignoring user's npm registry configuration. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1943

4. Installation risk: chrome-devtools-mcp: v0.20.1

• Severity: medium
• Finding: Installation risk is backed by a source signal: chrome-devtools-mcp: v0.20.1. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.20.1

5. Installation risk: chrome-devtools-mcp: v0.22.0

• Severity: medium
• Finding: Installation risk is backed by a source signal: chrome-devtools-mcp: v0.22.0. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.22.0

6. Configuration risk: chrome-devtools-mcp: v0.21.0

• Severity: medium
• Finding: Configuration risk is backed by a source signal: chrome-devtools-mcp: v0.21.0. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.21.0

7. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | README/documentation is current enough for a first validation pass.

8. Project risk: chrome-devtools-mcp: v0.20.0

• Severity: medium
• Finding: Project risk is backed by a source signal: chrome-devtools-mcp: v0.20.0. Treat it as a review item until the current version is checked.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.20.0

9. Project risk: chrome-devtools-mcp: v0.24.0

• Severity: medium
• Finding: Project risk is backed by a source signal: chrome-devtools-mcp: v0.24.0. Treat it as a review item until the current version is checked.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.24.0

10. Project risk: chrome-devtools-mcp: v0.26.0

• Severity: medium
• Finding: Project risk is backed by a source signal: chrome-devtools-mcp: v0.26.0. Treat it as a review item until the current version is checked.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/ChromeDevTools/chrome-devtools-mcp/releases/tag/chrome-devtools-mcp-v0.26.0

11. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | last_activity_observed missing

12. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | github_repo:1054793726 | https://github.com/ChromeDevTools/chrome-devtools-mcp | no_demo; severity=medium

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using chrome-devtools-mcp with real data or production workflows.

• Auto-connect doesn't work on WSL with mirrored networking (Chrome on Win - github / github_issue
• Close empty-object tool schemas for stricter MCP client validation - github / github_issue
• performance_start_trace records 'CPU throttling: none / Network throttli - github / github_issue
• Update check hardcodes registry.npmjs.org, ignoring user's npm registry - github / github_issue
• chrome-devtools-mcp: v0.26.0 - github / github_release
• chrome-devtools-mcp: v0.25.0 - github / github_release
• chrome-devtools-mcp: v0.24.0 - github / github_release
• chrome-devtools-mcp: v0.22.0 - github / github_release
• chrome-devtools-mcp: v0.21.0 - github / github_release
• chrome-devtools-mcp: v0.20.3 - github / github_release
• chrome-devtools-mcp: v0.20.1 - github / github_release
• chrome-devtools-mcp: v0.20.0 - github / github_release