# chromedevtools/chrome-devtools-mcp architecture

> Architecture diagram of the GitHub repository chromedevtools/chrome-devtools-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chromedevtools/chrome-devtools-mcp
- Repository: https://github.com/chromedevtools/chrome-devtools-mcp

## Overview

Chrome DevTools MCP is an MCP server and standalone CLI that lets an agent or terminal user automate and inspect a live Chrome browser. The main workflow is a client tool request, server dispatch and context acquisition, then browser interaction and a formatted result; the CLI is a separate entry point. The product also includes performance tracing, debugging, configuration, and usage telemetry. Edges are limited to relationships documented in the README or visible in the supplied source index and excerpts; several feature-module links are documented at the capability level rather than verified call paths.

Main entry points: [`src/index.ts`](https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/index.ts) (MCP server), [`src/ToolHandler.ts`](https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/ToolHandler.ts) (Tool handler), [`src/tools/ToolDefinition.ts`](https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts) (Tool definitions), [`src/McpContext.ts`](https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/McpContext.ts) (Browser context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_server["MCP server<br/>[index.ts]"]
  node_cli["Browser CLI<br/>[chrome-devtools.ts]"]
end

subgraph group_runtime["Server runtime"]
  node_handler["Tool handler<br/>[ToolHandler.ts]"]
  node_context["Browser context<br/>[McpContext.ts]"]
  node_tooldefs["Tool definitions<br/>[ToolDefinition.ts]"]
  node_formatter["Result formatting<br/>[McpResponse.ts]"]
end

subgraph group_browser["Browser capabilities"]
  node_browsermanager["Browser manager<br/>[BrowserManager.ts]"]
  node_page["Page automation<br/>[McpPage.ts]"]
  node_debugtools["Debug tools<br/>[console.ts]"]
  node_networktools["Network tools<br/>[network.ts]"]
  node_screenshot["Screenshots<br/>[screenshot.ts]"]
  node_performance["Performance analysis"]
  node_collectors["Page and worker logs<br/>[PageCollector.ts]"]
  node_heap["Heap snapshots"]
end

subgraph group_operations["Configuration and telemetry"]
  node_configparser["Config parser<br/>[ConfigParser.ts]"]
  node_serverconfig["Server configuration<br/>[ServerConfig.ts]"]
  node_telemetry["Usage telemetry<br/>[ClearcutLogger.ts]"]
end

node_agent(("MCP client"))
node_terminal(("CLI user"))
node_chrome["Chrome"]

node_agent -->|"sends tool requests"| node_server
node_terminal -->|"runs commands"| node_cli
node_server -->|"dispatches tools"| node_handler
node_handler -->|"gets context"| node_context
node_handler -->|"handles definitions"| node_tooldefs
node_handler -->|"handles response"| node_formatter
node_server -->|"configures browser"| node_browsermanager
node_browsermanager -->|"launches or connects"| node_chrome
node_tooldefs -->|"uses page APIs"| node_page
node_tooldefs -->|"uses heap manager"| node_heap
node_tooldefs -->|"uses trace processor"| node_performance
node_context -->|"uses collectors"| node_collectors
node_agent -.->|"requests debugging"| node_debugtools
node_agent -.->|"requests network inspection"| node_networktools
node_agent -.->|"requests screenshots"| node_screenshot
node_agent -.->|"requests performance analysis"| node_performance
node_server -->|"parses configuration"| node_configparser
node_configparser -->|"builds configuration"| node_serverconfig
node_server -->|"initializes telemetry"| node_telemetry

click node_server "https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/index.ts"
click node_cli "https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/bin/chrome-devtools.ts"
click node_handler "https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/ToolHandler.ts"
click node_context "https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/McpContext.ts"
click node_tooldefs "https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts"
click node_browsermanager "https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/BrowserManager.ts"
click node_page "https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/McpPage.ts"
click node_debugtools "https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/tools/console.ts"
click node_networktools "https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/tools/network.ts"
click node_screenshot "https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/tools/screenshot.ts"
click node_performance "https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/processors/PerformanceTrace.ts"
click node_collectors "https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/collectors/PageCollector.ts"
click node_heap "https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/processors/HeapSnapshotManager.ts"
click node_formatter "https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/McpResponse.ts"
click node_configparser "https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/config/ConfigParser.ts"
click node_serverconfig "https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/config/ServerConfig.ts"
click node_telemetry "https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/telemetry/ClearcutLogger.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_cli,node_agent,node_terminal toneBlue
class node_handler,node_context,node_tooldefs,node_formatter toneAmber
class node_browsermanager,node_page,node_debugtools,node_networktools,node_screenshot,node_performance,node_collectors,node_heap toneMint
class node_configparser,node_serverconfig,node_telemetry toneRose
class node_chrome toneIndigo
```

## Components

### Entry points

- [MCP server](https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/index.ts): `src/index.ts`
- [Browser CLI](https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/bin/chrome-devtools.ts): `src/bin/chrome-devtools.ts`

### Server runtime

- [Tool handler](https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/ToolHandler.ts): `src/ToolHandler.ts`
- [Browser context](https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/McpContext.ts): `src/McpContext.ts`
- [Tool definitions](https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/tools/ToolDefinition.ts): `src/tools/ToolDefinition.ts`
- [Result formatting](https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/McpResponse.ts): `src/McpResponse.ts`

### Browser capabilities

- [Browser manager](https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/BrowserManager.ts): `src/BrowserManager.ts`
- [Page automation](https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/McpPage.ts): `src/McpPage.ts`
- [Debug tools](https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/tools/console.ts): `src/tools/console.ts`
- [Network tools](https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/tools/network.ts): `src/tools/network.ts`
- [Screenshots](https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/tools/screenshot.ts): `src/tools/screenshot.ts`
- [Performance analysis](https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/processors/PerformanceTrace.ts): `src/processors/PerformanceTrace.ts`
- [Page and worker logs](https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/collectors/PageCollector.ts): `src/collectors/PageCollector.ts`
- [Heap snapshots](https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/processors/HeapSnapshotManager.ts): `src/processors/HeapSnapshotManager.ts`

### Configuration and telemetry

- [Config parser](https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/config/ConfigParser.ts): `src/config/ConfigParser.ts`
- [Server configuration](https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/config/ServerConfig.ts): `src/config/ServerConfig.ts`
- [Usage telemetry](https://github.com/chromedevtools/chrome-devtools-mcp/blob/main/src/telemetry/ClearcutLogger.ts): `src/telemetry/ClearcutLogger.ts`

### Other components

- **MCP client**
- **CLI user**
- **Chrome**

## Connections

- MCP client → MCP server: sends tool requests
- CLI user → Browser CLI: runs commands
- MCP server → Tool handler: dispatches tools (evidence: `src/index.ts`)
- Tool handler → Browser context: gets context (evidence: `src/ToolHandler.ts`)
- Tool handler → Tool definitions: handles definitions (evidence: `src/ToolHandler.ts`)
- Tool handler → Result formatting: handles response (evidence: `src/ToolHandler.ts`)
- MCP server → Browser manager: configures browser (evidence: `src/index.ts`)
- Browser manager → Chrome: launches or connects
- Tool definitions → Page automation: uses page APIs (evidence: `src/tools/ToolDefinition.ts`)
- Tool definitions → Heap snapshots: uses heap manager (evidence: `src/tools/ToolDefinition.ts`)
- Tool definitions → Performance analysis: uses trace processor (evidence: `src/tools/ToolDefinition.ts`)
- Browser context → Page and worker logs: uses collectors (evidence: `src/McpContext.ts`)
- MCP client → Debug tools: requests debugging
- MCP client → Network tools: requests network inspection
- MCP client → Screenshots: requests screenshots
- MCP client → Performance analysis: requests performance analysis
- MCP server → Config parser: parses configuration (evidence: `src/index.ts`)
- Config parser → Server configuration: builds configuration (evidence: `src/config/ConfigParser.ts`)
- MCP server → Usage telemetry: initializes telemetry (evidence: `src/index.ts`)
