chrome-devtools-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

chrome-devtools-mcp is an MCP (Model Context Protocol) server that enables AI coding agents to control and inspect a live Chrome browser. It acts as a bridge between MCP clients (like Claude, Cursor, Copilot) and Chrome DevTools, exposing 27 tools across categories: input automation, navigation, emulation, performance, network, and debugging.

Build & Development Commands

# Install dependencies
npm ci

# Build (clean, compile TypeScript, post-build processing, rollup)
npm run build

# Type checking without emitting files
npm run typecheck

# Format code (ESLint + Prettier)
npm run format

# Check formatting without fixing
npm run check-format

# Start the MCP server
npm run start

# Start with debug logging
npm run start-debug

# Run all tests
npm test

# Run only tests marked with test.only
npm run test:only

# Run only tests without rebuilding first
npm run test:only:no-build

# Update test snapshots
npm run test:update-snapshots

# Generate tool reference documentation
npm run docs:generate

# Full docs generation (build + generate + format)
npm run docs

Testing

The project uses Node.js built-in test runner. Test files are in tests/ directory mirroring the src/ structure.

Run a single test file:

npm run build && node --require ./build/tests/setup.js --no-warnings=ExperimentalWarning --test-reporter spec --test-force-exit --test build/tests/path/to/file.test.js

Run specific test with test.only:

npm run test:only

Architecture

Entry Point Flow

1. src/index.ts - Node version validation, imports main
2. src/main.ts - Server setup, tool registration, stdio transport
3. src/cli.ts - CLI argument parsing (yargs)
4. src/browser.ts - Browser launch/connection via Puppeteer

Core Components

McpContext (src/McpContext.ts)

• Central state management for browser sessions
• Manages pages, snapshots, network/console collectors
• Handles emulation states (CPU throttling, network conditions)
• Provides methods for page selection, element lookup by UID, dialog handling
• Implements timeout adjustments based on throttling multipliers