Overview

Browser DevTools MCP is a platform-extensible MCP server designed to give AI agents deep inspection and control over application runtimes. The architecture supports multiple platforms through a unified interface, with each platform providing specialized tools for its environment.

Supported Platforms

| Platform | Description | Status | |----------|-------------|--------| | Browser | Playwright-powered browser automation with full DevTools integration | ✅ Available | | Node | Non-blocking debugging for Node.js backend processes via Inspector Protocol | ✅ Available |

The Browser Platform exposes a Playwright-powered browser runtime to AI agents, enabling deep, bidirectional debugging and interaction with live web pages. It supports both visual understanding and code-level inspection of browser state, making it ideal for AI-driven exploration, diagnosis, and automation.

The Node Platform provides non-blocking debugging for Node.js backend processes. It connects to running Node.js processes via the Inspector Protocol (Chrome DevTools Protocol over WebSocket) and offers tracepoints, logpoints, exceptionpoints, watch expressions, and source map support—ideal for debugging APIs, workers, and server-side code.

Platform Selection

Choose the platform by running the appropriate MCP server or CLI:

| Use Case | MCP Server | CLI | |----------|------------|-----| | Browser automation & debugging | browser-devtools-mcp | browser-devtools-cli | | Node.js backend debugging | node-devtools-mcp | node-devtools-cli |

Browser Platform Capabilities

• Visual Inspection: Screenshots, ARIA snapshots, HTML/text extraction, PDF generation
• Design Comparison: Compare live page UI against Figma designs with similarity scoring
• DOM & Code-Level Debugging: Element inspection, computed styles, accessibility data
• Browser Automation: Navigation, input, clicking, scrolling, viewport control
• Execution Monitoring: Console message capture, HTTP request/response tracking
• OpenTelemetry Integration: Automatic trace injection into web pages, UI trace collection, and backend trace correlation via trace context propagation
• JavaScript Execution: Use the execute tool to batch-execute tool calls and run custom JavaScript; on the browser platform the VM receives `page` (Playwright Page) so you can use `page.evaluate()` or the Playwright API
• Session Management: Long-lived, session-based debugging with automatic cleanup
• Closed tab: If the MCP session’s browser tab was closed, the next tool run opens a new tab for that session (previous element refs are invalid until you take a new snapshot). Session network-idle / in-flight tracking state is also reset for the new tab.
• Multiple Transport Modes: Supports both stdio and HTTP transports

Node Platform Capabilities

• Connection: Connect to Node.js processes by PID, process name, port, WebSocket URL, or Docker container
• Non-Blocking Debugging: Tracepoints, logpoints, exceptionpoints without pausing execution
• Source Map Support: Resolves bundled/minified code to original source locations; debug_resolve-source-location translates stack traces and bundle locations to original source
• OpenTelemetry Integration: When the Node process uses @opentelemetry/api, tracepoint/logpoint snapshots automatically include traceContext (traceId, spanId) for correlating backend traces with browser traces
• Docker Support: Connect to Node.js processes running inside Docker containers (containerId / containerName)

Browser Platform Features

Content Tools

• Screenshots: Capture full page or specific elements (PNG/JPEG) with image data; optional annotate: true overlays numbered labels (1, 2, ...) on elements from the last ARIA snapshot refs and returns an annotations array (ref, number, role, name, box). If the ref map is empty, a snapshot is taken automatically. Set annotateContent: true to also include content elements (headings, list items, etc.) in the overlay. Set annotateCursorInteractive: true to also include cursor-interactive elements (clickable/focusable by CSS without ARIA role) in the overlay. The selector parameter accepts a ref (e.g. e1, @e1), a getByRole/getByLabel/getByText/etc. expression, or a CSS selector; with selector set, only annotations overlapping that element are returned and box coordinates are element-relative; with fullPage: true (no selector), box coordinates are document-relative.
• HTML/Text Extraction: Get page content with filtering, cleaning, and minification options
• PDF Export: Save pages as PDF documents with customizable format and margins
• Video Recording: Record browser page interactions as WebM video using CDP screencast. Start with content_start-recording, stop with content_stop-recording. Works in all modes (headless, headed, persistent, CDP attach). Chromium only.

Interaction Tools

• Click: Click elements by snapshot ref (e.g. e1, @e1, ref=e1), Playwright-style expression (e.g. getByRole('button', { name: 'Login' }), getByLabel('Email'), getByText('Register'), getByPlaceholder('[email protected]'), getByTitle('…'), getByAltText('…'), getByTestId('…')), or CSS selector. Refs come from a11y_take-aria-snapshot and are valid until the next snapshot or navigation.
• Fill: Fill form inputs (ref, getByRole/getByLabel/getByPlaceholder/etc., or CSS selector)
• Hover: Hover over elements (ref, getByXYZ expression, or CSS selector)
• Press Key: Simulate keyboard input; optional ref, getByXYZ expression, or CSS selector to focus an element before sending the key
• Select: Select dropdown options (ref, getByRole/getByTestId/etc., or CSS selector)
• Drag: Drag and drop (source and target as ref, getByXYZ expression, or CSS selector)
• Scroll: Scroll the page viewport or specific scrollable elements with multiple modes (by, to, top, bottom, left, right); optional ref, getByXYZ, or CSS selector for scrollable container
• Resize Viewport: Resize the page viewport using Playwright viewport emulation
• Resize Window: Resize the real browser window (OS-level) using Chrome DevTools Protocol

Navigation Tools

• Go To: Navigate to URLs with configurable wait strategies. By default waitForNavigation is true: after navigation completes, waits for network idle before taking snapshot/screenshot; set waitForNavigation: false to skip the network idle wait. waitForTimeoutMs (default 30000) is the timeout for that wait when waitForNavigation is true. By default (includeSnapshot: true) returns an ARIA snapshot with refs (output, refs); set includeSnapshot: false for url/status/ok only. Use snapshotOptions (e.g. interactiveOnly, cursorInteractive) to control which elements get refs (same as a11y_take-aria-snapshot). Optional includeScreenshot saves a screenshot to disk and returns screenshotFilePath; use screenshotOptions (outputPath, name, fullPage, type, annotate, includeBase64) — defaults: OS temp dir, name "screenshot"; set includeBase64: true only when the file cannot be read from the path (e.g. remote, container).
• Go Back / Go Forward: Navigate backward or forward in history. Same waitForNavigation (default true), waitForTimeoutMs, snapshot/refs and optional screenshot behavior as Go To.
• Reload: Reload the current page. Same waitForNavigation (default true), waitForTimeoutMs, snapshot/refs and optional screenshot behavior as Go To.

Execute tool (batch)

• Execute: Batch-execute multiple tool calls in a single request via custom JavaScript. Use callTool(name, input, returnOutput?) to invoke any registered tool (canonical id such as navigation_go-to, or the same name the MCP host exposes when TOOL_NAME_PREFIX is set). Reduces round-trips and token usage. Includes wall-clock timeout, max tool call limit (50), console log capture, and fail-fast error handling with failedTool diagnostics. On the browser platform the VM also receives the session execution context: page (Playwright Page) is available — use the Playwright API (e.g. page.locator(), page.goto()) or page.evaluate() to run script in the browser. On the Node platform no extra bindings are injected. CLI: run execute --code '…' [--timeout-ms N] or run execute --file ./script.js (same daemon session as other tools; starts the daemon if needed). Boolean tool flags with default true also accept --no-<flag> (e.g. --no-wait-for-navigation). MCP or daemon HTTP API (POST /call with toolName: "execute" and toolInput: { code, timeoutMs? }) also work.

Observability (O11Y) Tools

• Console Messages: Capture and filter browser console logs with advanced filtering (level, search, timestamp, sequence number)
• HTTP Requests: Monitor network traffic with filtering by resource type, status code, and more. Request headers, response headers, and response body are opt-in (includeRequestHeaders, includeResponseHeaders, includeResponseBody; default off). Response body is not stored for static assets (e.g. .js, .css, .map)
• Web Vitals: Collect Core Web Vitals (LCP, INP, CLS) and supporting metrics (TTFB, FCP) with ratings and recommendations based on Google's thresholds
• OpenTelemetry Tracing: Automatic trace injection into web pages, UI trace collection (document load, fetch, XMLHttpRequest, user interactions), and trace context propagation for backend correlation
• Trace ID Management: Get, set, and generate OpenTelemetry compatible trace IDs for distributed tracing across API calls

Scenario Tools

• Scenario Add/Update/Delete: Manage reusable test scenarios stored as JS scripts in .browser-devtools-mcp/scenarios.json (project-level or global)
• Scenario Run: Execute a saved scenario by name. Runs in the same sandbox as execute — supports callTool(), composable via nested scenario-run calls (max depth: 5)
• Scenario List: List all available scenarios from project and/or global scope
• Scenario Search: Search scenarios by description using configurable strategy (simple default or FTS5)

Synchronization Tools

• Wait for Network Idle: Wait until the page reaches a network-idle condition based on the session’s tracked in-flight request count (tunable via sync_wait-for-network-idle like idleTimeMs / maxConnections), useful for SPA pages and before taking screenshots

Accessibility (A11Y) Tools

• ARIA Snapshots: Capture semantic structure and accessibility roles in YAML format. Returns a tree with element refs (e1, e2, ...) and a refs map; refs are stored in session context for use in interaction tools (click, fill, hover, select, drag, scroll, press-key) as the selector (e.g. e1, @e1, ref=e1). You can also use Playwright-style expressions in those tools: getByRole('button', { name: 'Login' }), getByLabel('Email'), getByText('Register'), getByPlaceholder('…'), getByTitle('…'), getByAltText('…'), getByTestId('…'), or CSS selectors. Refs are valid until the next ARIA snapshot or navigation—re-snapshot after page/DOM changes. Options: interactiveOnly (only interactive elements get refs); cursorInteractive: true (also assign refs to elements that are clickable/focusable by CSS but have no ARIA role, e.g. custom div/span buttons); selector (scope the snapshot to an element).
• AX Tree Snapshots: Combine Chromium's Accessibility tree with runtime visual diagnostics (bounding boxes, visibility, occlusion detection, computed styles)

Stub Tools

• Intercept HTTP Request: Intercept and modify outgoing HTTP requests (headers, body, method) using glob patterns
• Mock HTTP Response: Mock HTTP responses (fulfill with custom status/headers/body or abort) with configurable delay, times limit, and probability (flaky testing)
• List Stubs: List all currently installed stubs for the active browser context
• Clear Stubs: Remove one or all installed stubs

Figma Tools

• Compare Page with Design: Compare the current page UI against a Figma design snapshot and return a combined similarity score using multiple signals (MSSIM, image embedding, text embedding)

React Tools

• Get Component for Element: Find React component(s) associated with a DOM element using React Fiber (best-effort)
• Get Element for Component: Map a React component instance to the DOM elements it renders by traversing the React Fiber graph

Important Requirements for React Tools:

• Persistent Browser Context: React tools work best with persistent browser context enabled (BROWSER_PERSISTENT_ENABLE=true)
• React DevTools Extension: For optimal reliability, manually install the "React Developer Tools" Chrome extension in the browser profile. The MCP server does NOT automatically install the extension.
  • Chrome Web Store: https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi
  • The extension enables reliable root discovery and component search via __REACT_DEVTOOLS_GLOBAL_HOOK__
  • Without the extension, tools fall back to scanning DOM for __reactFiber$ pointers (best-effort, less reliable)

Debug Tools (Non-Blocking)

Non-blocking debugging tools that capture snapshots without pausing execution. Ideal for AI-assisted debugging.

Probe Types:

• Tracepoint: Captures call stack, local variables, and async stack traces at a code location
• Logpoint: Evaluates and logs expressions without full debug context (lightweight)
• Exceptionpoint: Captures snapshots when exceptions occur (uncaught or all)

Core Operations (per probe type):

• put-*: Create a probe at a location
• remove-*: Remove a specific probe
• list-*: List all probes of a type
• clear-*: Remove all probes of a type
• get-*-snapshots: Retrieve captured snapshots (supports fromSequence for polling)
• clear-*-snapshots: Clear captured snapshots

Additional Tools:

• Resolve Source Location: Resolve a generated/bundle location (URL + line + column) to original source via source maps—useful for translating minified stack traces
• Watch Expressions: Add expressions to evaluate at every tracepoint/exceptionpoint hit
• Status: Get current debugging status (enabled, probe counts, snapshot stats)

Key Features:

• Source map support for debugging bundled/minified code with original source locations
• Automatic debugging enablement on first tool use
• Configurable limits (max snapshots, call stack depth, async segments)
• Sequence numbers for efficient snapshot polling
• OpenTelemetry trace context in Node snapshots (traceId, spanId when process uses @opentelemetry/api)
• Snapshot capture: 1 call stack frame with scopes (both platforms) to keep payloads small. Output trimming for get-probe-snapshots: default scopes = local only (both Browser and Node), 20 variables/scope. Override via maxCallStackDepth, includeScopes, maxVariablesPerScope.

Prerequisites

• Node.js 18+
• An AI assistant (with MCP client) like Cursor, Claude (Desktop or Code), VS Code, Windsurf, etc.

Quick Start

This MCP server (using STDIO or Streamable HTTP transport) can be added to any MCP Client like VS Code, Claude, Cursor, Windsurf, GitHub Copilot via the browser-devtools-mcp NPM package.

No manual installation required! The server can be run directly using npx, which automatically downloads and runs the package.

📦 Playwright browser binaries (required for browser platform)

The browser platform needs Playwright browser binaries (e.g. Chromium) to control the browser.
If you use npx to run the server, browsers are not downloaded at install time — you must install them once (see below). With a normal npm install, Playwright’s own packages may install Chromium automatically.

| Goal | What to do | |------|------------| | Install at first run (npx) | Set env before running: BROWSER_DEVTOOLS_INSTALL_CHROMIUM=true npx -y browser-devtools-mcp | | Install manually anytime | Run: npx playwright install chromium (or firefox, webkit) | | Skip download (CI / system browser) | Set: PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 |

1. Opt-in at install time — set env vars before npm install or npx so the postinstall script downloads the chosen browsers:

• Chromium (chromium + chromium-headless-shell + ffmpeg):

  BROWSER_DEVTOOLS_INSTALL_CHROMIUM=true npx -y browser-devtools-mcp

• Firefox: BROWSER_DEVTOOLS_INSTALL_FIREFOX=true
• WebKit: BROWSER_DEVTOOLS_INSTALL_WEBKIT=true Combine as needed, e.g. BROWSER_DEVTOOLS_INSTALL_CHROMIUM=true BROWSER_DEVTOOLS_INSTALL_FIREFOX=true npx -y browser-devtools-mcp.

2. Install via Playwright CLI (same global cache):

npx playwright install chromium   # or firefox, webkit

On Linux, include system dependencies:

npx playwright install --with-deps chromium

CLI Arguments

Browser DevTools MCP server supports the following CLI arguments for configuration:

• --transport <stdio|streamable-http> - Configures the transport protocol (defaults to stdio).
• --port <number> – Configures the port number to listen on when using streamable-http transport (defaults to 3000).

Install as AI Agent Skill

Install browser automation capabilities as a skill for AI coding agents (Claude Code, Cursor, Windsurf, etc.) using the skills.sh ecosystem:

npx skills add serkan-ozal/browser-devtools-skills

This installs the CLI skill that enables AI agents to automate browsers for web testing, screenshots, form filling, accessibility audits, performance analysis, and more. See the Skills Repository for details.

MCP Client Configuration

To use the Node platform (Node.js backend debugging), use node-devtools-mcp instead of browser-devtools-mcp:

{
  "mcpServers": {
    "node-devtools": {
      "command": "npx",
      "args": ["-y", "-p", "browser-devtools-mcp", "node-devtools-mcp"]
    }
  }
}

Alternatively, set PLATFORM=node when running browser-devtools-mcp.

Local Server

Add the following configuration into the claude_desktop_config.json file. See the Claude Desktop MCP docs for more info.

Browser platform (default):

→ Browser platform requires Playwright browser binaries. See 📦 Playwright browser binaries for one-time install (env vars or npx playwright install chromium).

{
  "mcpServers": {
    "browser-devtools": {
      "command": "npx",
      "args": ["-y", "browser-devtools-mcp"]
    }
  }
}

Node platform:

{
  "mcpServers": {
    "node-devtools": {
      "command": "npx",
      "args": ["-y", "-p", "browser-devtools-mcp", "node-devtools-mcp"]
    }
  }
}

Remote Server (HTTP Transport)

First, start the server with HTTP transport:

npx -y browser-devtools-mcp --transport=streamable-http --port=3000

Then, go to Settings > Connectors > Add Custom Connector in Claude Desktop and add the MCP server with:

• Name: Browser DevTools
• Remote MCP server URL: Point to where your server is hosted (e.g., http://localhost:3000/mcp if running locally, or https://your-server.com/mcp if hosted remotely)

Run the following command. See Claude Code MCP docs for more info.

→ Browser platform requires Playwright browser binaries. See 📦 Playwright browser binaries for one-time install (env vars or npx playwright install chromium).

Local Server

claude mcp add browser-devtools -- npx -y browser-devtools-mcp

Remote Server

First, start the server with HTTP transport:

npx -y browser-devtools-mcp --transport=streamable-http --port=3000

Then add the MCP server:

claude mcp add --transport http browser-devtools <SERVER_URL>

Replace <SERVER_URL> with your server URL (e.g., http://localhost:3000/mcp if running locally, or https://your-server.com/mcp if hosted remotely).

Add the following configuration into the ~/.cursor/mcp.json file (or .cursor/mcp.json in your project folder). See the Cursor MCP docs for more info.

→ Browser platform requires Playwright browser binaries. See 📦 Playwright browser binaries for one-time install (env vars or npx playwright install chromium).

Local Server

{
  "mcpServers": {
    "browser-devtools": {
      "command": "npx",
      "args": ["-y", "browser-devtools-mcp"]
    }
  }
}

Remote Server

First, start the server with HTTP transport:

npx -y browser-devtools-mcp --transport=streamable-http --port=3000

Then add the configuration:

{
  "mcpServers": {
    "browser-devtools": {
      "url": "<SERVER_URL>"
    }
  }
}

Replace <SERVER_URL> with your server URL (e.g., http://localhost:3000/mcp if running locally, or https://your-server.com/mcp if hosted remotely).

Add the following configuration into the .vscode/mcp.json file. See the VS Code MCP docs for more info.

→ Browser platform requires Playwright browser binaries. See 📦 Playwright browser binaries for one-time install (env vars or npx playwright install chromium).

Local Server

{
  "mcp": {
    "servers": {
      "browser-devtools": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "browser-devtools-mcp"]
      }
    }
  }
}

Remote Server

First, start the server with HTTP transport:

npx -y browser-devtools-mcp --transport=streamable-http --port=3000

Then add the configuration:

{
  "mcp": {
    "servers": {
      "browser-devtools": {
        "type": "http",
        "url": "<SERVER_URL>"
      }
    }
  }
}

Replace <SERVER_URL> with your server URL (e.g., http://localhost:3000/mcp if running locally, or https://your-server.com/mcp if hosted remotely).

Add the following configuration into the ~/.codeium/windsurf/mcp_config.json file. See the Windsurf MCP docs for more info.

→ Browser platform requires Playwright browser binaries. See 📦 Playwright browser binaries for one-time install (env vars or npx playwright install chromium).

Local Server

{
  "mcpServers": {
    "browser-devtools": {
      "command": "npx",
      "args": ["-y", "browser-devtools-mcp"]
    }
  }
}

Remote Server

First, start the server with HTTP transport:

npx -y browser-devtools-mcp --transport=streamable-http --port=3000

Then add the configuration:

{
  "mcpServers": {
    "browser-devtools": {
      "serverUrl": "<SERVER_URL>"
    }
  }
}

Replace <SERVER_URL> with your server URL (e.g., http://localhost:3000/mcp if running locally, or https://your-server.com/mcp if hosted remotely).

Add the following configuration to the mcpServers section of your Copilot Coding Agent configuration through Repository > Settings > Copilot > Coding agent > MCP configuration. See the Copilot Coding Agent MCP docs for more info.

→ Browser platform requires Playwright browser binaries. See 📦 Playwright browser binaries for one-time install (env vars or npx playwright install chromium).

Local Server

{
  "mcpServers": {
    "browser-devtools": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "browser-devtools-mcp"]
    }
  }
}

Remote Server

First, start the server with HTTP transport:

npx -y browser-devtools-mcp --transport=streamable-http --port=3000

Then add the configuration:

{
  "mcpServers": {
    "browser-devtools": {
      "type": "http",
      "url": "<SERVER_URL>"
    }
  }
}

Replace <SERVER_URL> with your server URL (e.g., http://localhost:3000/mcp if running locally, or https://your-server.com/mcp if hosted remotely).

Add the following configuration into the ~/.gemini/settings.json file. See the Gemini CLI MCP docs for more info.

Local Server

{
  "mcpServers": {
    "browser-devtools": {
      "command": "npx",
      "args": ["-y", "browser-devtools-mcp"]
    }
  }
}

Remote Server

First, start the server with HTTP transport:

npx -y browser-devtools-mcp --transport=streamable-http --port=3000

Then add the configuration:

{
  "mcpServers": {
    "browser-devtools": {
      "httpUrl": "<SERVER_URL>"
    }
  }
}

Replace <SERVER_URL> with your server URL (e.g., http://localhost:3000/mcp if running locally, or https://your-server.com/mcp if hosted remotely).

Run the following command. You can find your Smithery API key here. See the Smithery CLI docs for more info.

npx -y @smithery/cli install serkan-ozal/browser-devtools-mcp --client <SMITHERY-CLIENT-NAME> --key <SMITHERY-API-KEY>

HTTP Transport

To use HTTP transport, start the server with:

npx -y browser-devtools-mcp --transport=streamable-http --port=3000

The server exposes the following endpoints:

• GET /health - Health check
• GET /ping - Ping endpoint
• GET /mcp - MCP protocol info
• POST /mcp - MCP protocol messages
• DELETE /mcp - Delete session

Important: When configuring remote MCP servers, use the actual URL where your server is hosted:

• If running locally: http://localhost:3000/mcp (or http://127.0.0.1:3000/mcp)
• If hosted remotely: https://your-server.com/mcp (replace with your actual server URL)

MCP Inspector

Test the server using the MCP Inspector:

# For stdio transport
npx -y @modelcontextprotocol/inspector npx -y browser-devtools-mcp

# For HTTP transport (start server first)
npx -y browser-devtools-mcp --transport=streamable-http --port=3000
# Then in another terminal:
npx -y @modelcontextprotocol/inspector http://localhost:3000/mcp --transport http

CLI Tools

Browser DevTools MCP includes standalone CLI tools for both platforms:

• browser-devtools-cli: Browser platform—navigation, screenshots, interaction, a11y, debugging, etc.
• node-devtools-cli: Node platform—connect to Node.js processes, tracepoints, logpoints, exceptionpoints

This is particularly useful for:

• Scripting and automation: Use in shell scripts, CI/CD pipelines, or automated workflows
• Session-based testing: Maintain browser state across multiple commands with session IDs
• Skill-based workflows: Build reusable automation sequences

Installation

The CLIs are included with the npm package:

# Run directly with npx
npx -y browser-devtools-cli --help
npx -y node-devtools-cli --help

# Or install globally
npm install -g browser-devtools-mcp
browser-devtools-cli --help
node-devtools-cli --help

To install Playwright browser binaries (required for the browser CLI when not using a system browser), run npx playwright install chromium (see Playwright browser binaries).

Global Options

| Option | Description | Default | |--------|-------------|---------| | --port <number> | Daemon server port | 2020 | | --session-id <string> | Session ID for maintaining browser state across commands | (none) | | --json | Output results as JSON | false | | --quiet | Suppress log messages, only show output | false | | --verbose | Enable verbose/debug output for troubleshooting | false | | --timeout <ms> | Timeout for operations in milliseconds | 30000 | | --no-telemetry | Disable anonymous usage telemetry for this invocation | false |

Browser Options

| Option | Description | Default | |--------|-------------|---------| | --headless / --no-headless | Run browser in headless (no visible window) or headful mode | true | | --persistent / --no-persistent | Use persistent browser context (preserves cookies, localStorage) | false | | --user-data-dir <path> | Directory for persistent browser context user data | ./browser-devtools-mcp | | --use-system-browser | Use system-installed Chrome instead of bundled browser | false | | --browser-path <path> | Custom browser executable path | (none) |

Note: Browser options are applied when the daemon server starts. If the daemon is already running, stop it first (daemon stop) then start with new options.

Node CLI Commands

node-devtools-cli provides Node.js backend debugging:

node-devtools-cli
├── daemon                    # Manage the daemon server
├── session                   # Manage Node.js debugging sessions
├── tools                     # List and inspect available tools
├── config                    # Show current configuration
├── completion                # Generate shell completion scripts
├── interactive (repl)        # Start interactive REPL mode
├── update                    # Check for updates
└── debug                     # Debug commands
    ├── connect               # Connect to Node.js process (pid, processName, inspectorPort, containerId, etc.)
    ├── disconnect            # Disconnect from current process
    ├── status                # Show connection status
    ├── put-tracepoint        # Set a tracepoint
    ├── put-logpoint          # Set a logpoint
    ├── put-exceptionpoint    # Configure exception catching
    └── ...                   # Watch, snapshots, probes management

Browser CLI Commands

browser-devtools-cli organizes tools into domain-based subcommands. Object parameters (e.g. screenshotOptions, snapshotOptions) must be passed as a JSON string: --screenshot-options '{"outputPath":"/tmp","name":"myshot"}' or --snapshot-options '{"interactiveOnly":false}'. Boolean parameters with default true can be turned off with --no-<kebab-flag> (e.g. --no-wait-for-navigation). Run browser-devtools-cli navigation go-to --help (or the relevant subcommand) to see all options.

browser-devtools-cli
├── daemon                    # Manage the daemon server
│   ├── start                 # Start the daemon server
│   ├── stop                  # Stop the daemon server
│   ├── restart               # Restart the daemon server (stop + start)
│   ├── status                # Check daemon server status
│   └── info                  # Get detailed daemon info (version, uptime, sessions)
├── session                   # Manage browser sessions
│   ├── list                  # List all active sessions
│   ├── info <session-id>     # Get information about a session
│   └── delete <session-id>   # Delete a specific session
├── tools                     # Inspect available tools
│   ├── list                  # List all tools (with --domain filter)
│   ├── info <tool-name>      # Get detailed tool info and parameters
│   └── search <query>        # Search tools by name or description
├── config                    # Show current configuration
├── completion                # Generate shell completion scripts
│   ├── bash                  # Generate bash completion script
│   └── zsh                   # Generate zsh completion script
├── interactive (repl)        # Start interactive REPL mode
├── update                    # Check for and install updates
├── navigation                # Navigation commands
│   ├── go-to                 # Navigate to a URL
│   ├── go-back-or-forward    # Navigate back or forward in history (direction: back | forward)
│   └── reload                # Reload the page
├── content                   # Content extraction commands
│   ├── take-screenshot       # Take a screenshot
│   ├── get-as-html           # Get HTML content
│   ├── get-as-text           # Get text content
│   └── save-as-pdf           # Save as PDF
├── interaction               # Interaction commands
│   ├── click                 # Click an element
│   ├── fill                  # Fill a form field
│   ├── hover                 # Hover over an element
│   ├── press-key             # Press a keyboard key
│   ├── select                # Select from dropdown
│   ├── drag                  # Drag and drop
│   ├── scroll                # Scroll the page
│   ├── resize-viewport       # Resize viewport
│   └── resize-window         # Resize browser window
├── a11y                      # Accessibility commands
│   └── take-aria-snapshot    # Take ARIA snapshot
├── accessibility             # Extended accessibility commands
│   └── take-ax-tree-snapshot # Take AX tree snapshot
├── o11y                      # Observability commands
│   ├── get-console-messages  # Get console logs
│   ├── get-http-requests     # Get HTTP requests
│   ├── get-web-vitals        # Get Web Vitals metrics
│   ├── get-trace-context     # Get current trace context
│   ├── new-trace-id          # Generate new trace ID
│   └── set-trace-context     # Set trace context
├── react                     # React debugging commands
│   ├── get-component-for-element
│   └── get-element-for-component
├── run                       # Batch execute (MCP parity): run execute --code '…' or --file path.js
│   └── execute
├── stub                      # HTTP stubbing commands
│   ├── mock-http-response    # Mock HTTP responses
│   ├── intercept-http-request # Intercept requests
│   ├── list                  # List stubs
│   └── clear                 # Clear stubs
├── sync                      # Synchronization commands
│   └── wait-for-network-idle # Wait for network idle (configurable idle time / threshold)
├── debug                     # Non-blocking debugging commands
│   ├── put-tracepoint        # Set a tracepoint (captures call stack)
│   ├── remove-probe         # Remove a tracepoint, logpoint, or watch by ID (type + id)
│   ├── list-probes           # List tracepoints, logpoints, and/or watches (optional types; omit to list all)
│   ├── put-logpoint          # Set a logpoint (evaluates expression)
│   ├── put-exceptionpoint    # Enable exception catching
│   ├── add-watch             # Add a watch expression
│   ├── clear-probes          # Clear tracepoints, logpoints, and/or watches (optional types; omit to clear all)
│   ├── get-probe-snapshots           # Get tracepoint/logpoint/exceptionpoint snapshots (1 frame captured; default scopes: local only; 20 vars/scope; override: maxCallStackDepth, includeScopes, maxVariablesPerScope)
│   ├── clear-probe-snapshots         # Clear tracepoint/logpoint/exceptionpoint snapshots (optional types; omit to clear all)
│   └── status                # Get debugging status
└── figma                     # Figma integration commands
    └── compare-page-with-design

Usage Examples

Basic Navigation and Screenshot

# Navigate to a URL
browser-devtools-cli navigation go-to --url "https://example.com"

# Take a screenshot
browser-devtools-cli content take-screenshot --name "homepage"

Browser Options

Configure browser behavior when starting the daemon:

# Run browser in headful mode (visible window)
browser-devtools-cli --no-headless navigation go-to --url "https://example.com"

# Use persistent browser context
browser-devtools-cli --persistent --user-data-dir ./my-profile navigation go-to --url "https://example.com"

# Use system Chrome instead of bundled Chromium
browser-devtools-cli --use-system-browser navigation go-to --url "https://example.com"

# Use a custom browser executable
browser-devtools-cli --browser-path /path/to/chrome navigation go-to --url "https://example.com"

Session-Based Workflow

Maintain browser state across multiple commands using session IDs:

# Start a session and navigate
browser-devtools-cli --session-id my-session navigation go-to --url "https://example.com"

# Interact with the page (same session)
browser-devtools-cli --session-id my-session interaction click --selector "button.login"

# Fill a form
browser-devtools-cli --session-id my-session interaction fill --selector "#username" --value "[email protected]"

# Take a screenshot
browser-devtools-cli --session-id my-session content take-screenshot --name "after-login"

# Clean up session when done
browser-devtools-cli session delete my-session

JSON Output for Scripting

Use --json and --quiet flags for machine-readable output:

# Get page content as JSON
browser-devtools-cli --json --quiet --session-id test navigation go-to --url "https://api.example.com"

# Output:
# {
#   "url": "https://api.example.com/",
#   "status": 200,
#   "statusText": "",
#   "ok": true
# }

Daemon Management

# Check daemon status
browser-devtools-cli daemon status

# Start daemon manually
browser-devtools-cli daemon start

# Stop daemon
browser-devtools-cli daemon stop

# Restart daemon (useful when changing browser options)
browser-devtools-cli daemon restart

# Check status with JSON output
browser-devtools-cli daemon status --json
# Output: {"status":"running","port":2020}

# Get detailed daemon information
browser-devtools-cli daemon info
# Output:
# Daemon Server Information:
#   Version:       0.5.0
#   Port:          2020
#   Uptime:        5m 23s
#   Sessions:      2

Session Management

# List all active sessions
browser-devtools-cli session list
# Output:
# Active Sessions (2):
#   my-session
#     Created:     2025-01-26T10:00:00.000Z
#     Last Active: 2025-01-26T10:05:30.000Z
#     Idle:        30s
#   #default
#     Created:     2025-01-26T09:55:00.000Z
#     Last Active: 2025-01-26T10:04:00.000Z
#     Idle:        1m 30s

# Get info about a specific session
browser-devtools-cli session info my-session

# Delete a session
browser-devtools-cli session delete my-session

Tool Discovery

# List all available tools
browser-devtools-cli tools list
# Output:
# Available Tools (35 total):
#
#   navigation:
#     go-to                          Navigate the browser to the given URL...
#     go-back-or-forward             Navigate back or forward in history (direction: back | forward)
#     ...

# Filter tools by domain
browser-devtools-cli tools list --domain interaction

# Search for tools by keyword
browser-devtools-cli tools search click
# Output:
# Tools matching "click" (2 found):
#
#   interaction/click
#     Clicks an element on the page.
#   ...

# Get detailed info about a specific tool
browser-devtools-cli tools info navigation_go-to
# Output:
# Tool: navigation_go-to
# Domain: navigation
#
# Description:
#   Navigate the browser to the given URL...
#
# Parameters:
#   --url <string> (required)
#       The URL to navigate to
#   --wait-until <load | domcontentloaded | commit> (optional)
#       When to consider navigation succeeded
#       Default: "load"
#
# Usage:
#   browser-devtools-cli navigation go-to [options]

Configuration

# Show current configuration
browser-devtools-cli config
# Output:
# Current Configuration:
#
#   Daemon:
#     Port:                    2020
#     Session Idle (sec):      300
#     Idle Check Interval:     30
#
#   Browser:
#     Headless:                true
#     Persistent:              false
#     ...

# Show config as JSON
browser-devtools-cli config --json

Verbose/Debug Mode

Enable verbose output for troubleshooting:

# Run any command with --verbose for detailed debug logs
browser-devtools-cli --verbose navigation go-to --url "https://example.com"
# Output:
# [2025-01-26T10:00:00.000Z] [DEBUG] Verbose mode enabled
# [2025-01-26T10:00:00.001Z] [DEBUG] CLI version: 0.5.0
# [2025-01-26T10:00:00.001Z] [DEBUG] Node version: v20.10.0
# [2025-01-26T10:00:00.001Z] [DEBUG] Platform: darwin
# [2025-01-26T10:00:00.002Z] [DEBUG] Checking if daemon is running on port 2020
# [2025-01-26T10:00:00.010Z] [DEBUG] Daemon health check result: running
# [2025-01-26T10:00:00.011Z] [DEBUG] Calling tool: navigation_go-to
# [2025-01-26T10:00:00.011Z] [DEBUG] Tool input: { url: "https://example.com" }
# ...

Tool Search

Find tools by keyword:

# Search for tools related to "screenshot"
browser-devtools-cli tools search screenshot
# Output:
# Tools matching "screenshot" (2 found):
#
#   content/take-screenshot
#     Takes a screenshot of the current page or a specific element.
#
#   figma/compare-page-with-design
#     Compares the CURRENT PAGE UI against a Figma design snapshot...

# Search for tools related to "network"
browser-devtools-cli tools search network

Shell Completions

Enable tab completion for faster command entry. Shell completions require a one-time setup:

For Bash:

# Option 1: Add to ~/.bashrc (recommended)
echo 'eval "$(browser-devtools-cli completion bash)"' >> ~/.bashrc
source ~/.bashrc

# Option 2: Or add manually to ~/.bashrc
eval "$(browser-devtools-cli completion bash)"

For Zsh (macOS default):

# Option 1: Add to ~/.zshrc (recommended)
echo 'eval "$(browser-devtools-cli completion zsh)"' >> ~/.zshrc
source ~/.zshrc

# Option 2: Or add manually to ~/.zshrc
eval "$(browser-devtools-cli completion zsh)"

Using with npx:

# If using npx instead of global install:
echo 'eval "$(npx -y browser-devtools-cli completion zsh)"' >> ~/.zshrc
source ~/.zshrc

After setup, press TAB for completions:

browser-devtools-cli dae<TAB>        # Completes to "daemon"
browser-devtools-cli daemon st<TAB>  # Shows "start", "stop", "status", "restart"
browser-devtools-cli --<TAB>         # Shows all global options

Interactive REPL Mode

Start an interactive session for continuous command entry:

# Start in headless mode (default)
browser-devtools-cli interactive

# Start with visible browser window
browser-devtools-cli --no-headless interactive

# Start with persistent context (preserves cookies, localStorage)
browser-devtools-cli --no-headless --persistent interactive

# Aliases
browser-devtools-cli repl
browser-devtools-cli --no-headless repl

Example session:

Browser DevTools CLI - Interactive Mode
Type "help" for available commands, "exit" to quit

browser> navigation go-to --url "https://example.com"
url: https://example.com/
status: 200
ok: true

browser> content take-screenshot --name "homepage"
path: /path/to/homepage.png

browser> interaction click --ref "Login"
clicked: true

browser> interaction fill --ref "Email" --value "[email protected]"
filled: true

browser> tools search screenshot
Found 2 tools:
  content_take-screenshot - Take a screenshot of the current page
  content_save-as-pdf - Save the current page as a PDF file

browser> daemon info
Version: 0.5.0
Uptime: 5m 23s
Sessions: 1
Port: 2020

browser> session list
Active sessions: 1
  #default (idle: 30s)

browser> config
Current Configuration:
  port = 2020
  headless = false
  persistent = true
  ...

browser> exit
Goodbye!

Available commands in interactive mode:

| Command | Description | |---------|-------------| | help | Show available commands | | exit, quit | Exit interactive mode | | status | Show daemon status summary | | config | Show current configuration | | daemon <cmd> | Daemon management (start, stop, restart, status, info) | | session <cmd> | Session management (list, info, delete) | | tools <cmd> | Tool discovery (list, search, info) | | update | Check for CLI updates | | <domain> <tool> | Execute a tool |

Check for Updates

Keep your CLI up to date:

# Check for updates without installing
browser-devtools-cli update --check
# Output:
# Checking for updates...
#
#   Current version:  0.5.0
#   Latest version:   0.5.1
#
# ⚠ Update available: 0.5.0 → 0.5.1
#
# To update, run:
#   npm install -g browser-devtools-mcp@latest

# Check and install updates interactively
browser-devtools-cli update
# Output:
# ...
# Do you want to update now? (y/N) y
# Updating...
# ✓ Update complete!

Shell Script Example

#!/bin/bash
SESSION="test-$(date +%s)"
CLI="browser-devtools-cli --json --quiet --session-id $SESSION"

# Navigate
$CLI navigation go-to --url "https://example.com"

# Get text content
CONTENT=$($CLI content get-as-text)
echo "Page content: $CONTENT"

# Take screenshot
$CLI content take-screenshot --name "test-result"

# Cleanup
browser-devtools-cli session delete $SESSION

Daemon Architecture

The CLI uses a daemon server architecture for efficient browser management:

1. Auto-start: The daemon starts automatically when you run any tool command
2. Shared browser: Multiple CLI invocations share the same browser instance
3. Session isolation: Each session ID gets its own isolated browser context
4. Auto-cleanup: Idle sessions are automatically cleaned up after inactivity
5. Full tool set: The daemon exposes the same tools as MCP (including execute for batch execution). Most tools map to domain subcommands (e.g. navigation go-to). execute maps to run execute (not listed under tools list, which only reflects the static tool registry).
6. Platform env: The browser CLI forces PLATFORM=browser on the daemon it spawns (and the Node CLI forces PLATFORM=node), so a shell-wide PLATFORM=node cannot accidentally make browser-devtools-cli start a Node-platform daemon. If you still see errors, check error.message on failed POST /call responses — the daemon includes the underlying exception message there.

The daemon listens on port 2020 by default. Use --port to specify a different port.

CLI Skills Documentation

Comprehensive documentation for AI agents and automation is available in the browser-devtools-skills repository.

Install as an AI agent skill:

npx skills add serkan-ozal/browser-devtools-skills

For the full list of available skills and documentation, see the browser-devtools-skills repository.

Configuration

The server can be configured using environment variables. Configuration is divided into server-level settings and platform-specific settings.

Server Configuration

| Variable | Description | Default | |----------|-------------|---------| | PORT | Port for HTTP transport | 3000 | | TELEMETRY_ENABLE | Set to false to disable anonymous usage telemetry | (unset) | | SESSION_IDLE_SECONDS | Idle session timeout (seconds) | 300 | | SESSION_IDLE_CHECK_SECONDS | Interval for checking idle sessions (seconds) | 30 | | SESSION_CLOSE_ON_SOCKET_CLOSE | Close session when socket closes | false | | TOOL_OUTPUT_SCHEMA_DISABLE | When true, omit tool output schema from MCP tool registration (can reduce token usage for some clients) | false | | TOOL_NAME_PREFIX | Optional string prepended to every MCP-registered tool name (stdio / streamable HTTP only), including execute. MCP-facing TypeScript text is rewritten by applyNormalizedToolNamesInText in src/config.ts: only angle-bracket-wrapped substrings that match a registered canonical tool id are replaced with the prefixed name, so plain words like “execute” are never rewritten. README and non-MCP comments should use backticks only, e.g. navigation_go-to and callTool('navigation_go-to', …). In normalized sources (tool descriptions, server instructions, execute templates), authors wrap cross-tool references in angle brackets inside those string literals so clients receive the correct prefixed names. ToolRegistry.runTool also accepts a name that is a single bracket-wrapped id. Unrelated bracket tokens are left unchanged. CLI is unchanged. | (unset) | | AVAILABLE_TOOL_DOMAINS | Optional comma-separated list of tool domains to enable. When set, only tools from these domains are registered; unset means all tools. Browser domains: a11y, content, debug, figma, interaction, navigation, o11y, react, run, stub, sync. Node domains: debug, run. Example: AVAILABLE_TOOL_DOMAINS=navigation,interaction,a11y | (all tools) |

Tool inputs are validated with a strict schema; unknown or misspelled argument keys (e.g. port instead of inspectorPort) cause a validation error.

Node Platform Configuration

| Variable | Description | Default | |----------|-------------|---------| | NODE_SERVER_INSTRUCTIONS_ENABLE | When true, include server instructions in MCP server info | true | | NODE_POLICY_DEBUGGING_ENABLE | When true, include NODE_DEBUGGING_POLICY in server policies | false | | NODE_CONSOLE_MESSAGES_BUFFER_SIZE | Maximum console messages to buffer from Node.js process | 1000 | | NODE_INSPECTOR_HOST | Inspector host for debug_connect when MCP runs in Docker (e.g. host.docker.internal). Use with host-mapped inspectorPort so the MCP connects to the right address. | 127.0.0.1 | | PLATFORM | Platform to use: browser or node | browser |

Browser Platform Configuration

| Variable | Description | Default | |----------|-------------|---------| | BROWSER_SERVER_INSTRUCTIONS_ENABLE | When true, include server instructions in MCP server info | true | | BROWSER_POLICY_UI_DEBUGGING_ENABLE | When true, include UI_DEBUGGING_POLICY in server policies | false | | CONSOLE_MESSAGES_BUFFER_SIZE | Maximum console messages to buffer | 1000 | | HTTP_REQUESTS_BUFFER_SIZE | Maximum HTTP requests to buffer | 1000 | | BROWSER_HEADLESS_ENABLE | Run browser in headless mode | true | | BROWSER_PERSISTENT_ENABLE | Use persistent browser context (preserves cookies, localStorage, etc.). Required for React tools to work optimally. | false | | BROWSER_PERSISTENT_USER_DATA_DIR | Directory for persistent browser context user data | ./browser-devtools-mcp | | BROWSER_CDP_ENDPOINT_URL | CDP attach: http://host:port, or ws://… directly. HTTP URLs are resolved like agent-browser (/json/version, /json/list, then ws://…/devtools/browser). Chromium only. | (unset) | | BROWSER_CDP_ENABLE | When true and no endpoint URL: probes 127.0.0.1:9222 then :9229 (HTTP + WebSocket CDP discovery). With BROWSER_CDP_ENDPOINT_URL, connects only to that host/port. | false | | BROWSER_CDP_OPEN_INSPECT | On loopback CDP failure, if Chrome is running, opens chrome://inspect/#remote-debugging so you can enable remote debugging. The server does not start Chrome — start it yourself with --remote-debugging-port=9222. Set false to never open. | true | | BROWSER_USE_INSTALLED_ON_SYSTEM | Use system-installed Chrome browser instead of Playwright's bundled browser | false | | BROWSER_EXECUTABLE_PATH | Custom browser executable path | (uses Playwright default) | | OTEL_ENABLE | Enable OpenTelemetry integration | false | | OTEL_SERVICE_NAME | OpenTelemetry service name | frontend | | OTEL_SERVICE_VERSION | OpenTelemetry service version | (none) | | OTEL_ASSETS_DIR | Directory containing OpenTelemetry bundle files | (uses default) | | OTEL_EXPORTER_TYPE | OpenTelemetry exporter type: "otlp/http-json", "otlp/http-protobuf", "console", or "none" (alias: "otlp/http" = "otlp/http-json") | none | | OTEL_EXPORTER_HTTP_URL | OpenTelemetry collector base URL (e.g., "http://localhost:4318") | (none) | | OTEL_EXPORTER_HTTP_HEADERS | OpenTelemetry exporter HTTP headers (comma-separated key=value pairs) | (none) | | OTEL_INSTRUMENTATION_USER_INTERACTION_EVENTS | User interaction events to instrument (comma-separated, e.g., "click,submit") | click | | FIGMA_ACCESS_TOKEN | Figma API access token for design comparison | (none) | | FIGMA_API_BASE_URL | Figma API base URL | https://api.figma.com/v1 |

CDP attach (no auto-launch)

When BROWSER_CDP_ENABLE or BROWSER_CDP_ENDPOINT_URL is set, the server only attaches to an existing Chrome that already exposes CDP (e.g. started with --remote-debugging-port=9222). Without an explicit URL it tries 9222 then 9229 on loopback; with BROWSER_CDP_ENDPOINT_URL it uses that host/port only. It verifies reachability, then connectOverCDP. context.newPage() opens a new tab in that browser.

If CDP is not reachable on loopback and Chrome appears to be running, BROWSER_CDP_OPEN_INSPECT (default true) opens chrome://inspect/#remote-debugging so you can turn on remote debugging. Start Chrome with debugging, then retry the tool.

CDP errors (what the message means)

| Prefix | Stage | Typical cause | |--------|--------|----------------| | [CDP discovery] | Finding the DevTools port / URL | Chrome not in remote-debugging mode, wrong URL, or nothing listening on the probed port(s). | | [CDP connect] | Playwright connectOverCDP | Approve Chrome’s remote-debugging prompt; or set BROWSER_CDP_ENDPOINT_URL to the correct ws:// / http:// endpoint. |

Telemetry

Browser DevTools MCP collects anonymous usage data to understand which tools are used, detect errors, and improve the product over time. Telemetry is opt-out — it is enabled by default and can be disabled at any time with zero friction.

What is collected

Only non-personal, non-sensitive data is sent. No page content, URLs, error messages, or any application-specific data is ever included.

Events: tool_called (each tool invocation), mcp_server_started (MCP server is ready to accept traffic — stdio after the transport is connected, streamable HTTP after the listener is bound), and cli_command_executed (CLI subcommands).

| Property | Description | |----------|-------------| | tool_name | Name of the tool that was called | | source | How the tool was invoked (see table below) | | duration_ms | Tool execution time in milliseconds | | success | Whether the call succeeded (true / false) | | error_type | Error class name (e.g. TypeError) — only on failure | | error_code | Error code (e.g. ECONNREFUSED) — only on failure | | browser_devtools_version | Package version (e.g. 0.2.27) | | node_version | Node.js runtime version (e.g. v20.10.0) | | os_platform | Operating system (e.g. darwin, linux, win32) | | os_arch | CPU architecture (e.g. x64, arm64) | | timezone | Local timezone (e.g. America/New_York) | | timestamp | UTC timestamp of the event | | session_id | MCP session ID from the transport (MCP only) | | client_name | Raw MCP client name from the initialize handshake (MCP only) | | transport | MCP transport in use — stdio or streamable-http (mcp_server_started only) |

What is never collected:

• Any personally identifiable information (PII)
• error.message content — only the error class name and code are sent
• URLs, page content, screenshots, or any application data

A persistent anonymous UUID is stored locally at ~/.browser-devtools-mcp/config.json. It is never linked to any user identity.

Source values

The source field identifies the calling context:

| Value | Meaning | |-------|---------| | cli | Called via browser-devtools-cli or node-devtools-cli | | cli_cursor | CLI invoked from within Cursor (env var with CURSOR_ prefix detected) | | cli_claude | CLI invoked from within Claude (env var with CLAUDE_ prefix detected) | | cli_codex | CLI invoked from within Codex (env var with CODEX_ prefix detected) | | mcp-cursor | MCP client is Cursor | | mcp-claude | MCP client is Claude Desktop or Claude Code | | mcp-codex | MCP client is OpenAI Codex CLI | | mcp-unknown | MCP client could not be identified |

How to disable telemetry

MCP server — set TELEMETRY_ENABLE=false in your MCP client config:

{
  "mcpServers": {
    "browser-devtools": {
      "command": "npx",
      "args": ["-y", "browser-devtools-mcp"],
      "env": { "TELEMETRY_ENABLE": "false" }
    }
  }
}

CLI — pass --no-telemetry to any command:

browser-devtools-cli --no-telemetry navigation go-to --url "https://example.com"

To disable telemetry permanently for all CLI invocations, add an alias to your shell profile:

# ~/.zshrc or ~/.bashrc
alias browser-devtools-cli="browser-devtools-cli --no-telemetry"

Once disabled, no data is sent and no network requests are made to PostHog.

Browser Platform Tools

Content Tools

Parameters:

• outputPath (string, optional): Directory path where screenshot will be saved (default: OS temp directory)
• name (string, optional): Screenshot name (default: "screenshot")
• selector (string, optional): Ref (e.g. e1, @e1), getByRole/getByLabel/getByText/getByPlaceholder/getByTitle/getByAltText/getByTestId expression, or CSS selector for element to capture
• fullPage (boolean, optional): Capture full scrollable page (default: false)
• type (enum, optional): Image format - "png" or "jpeg" (default: "png")
• quality (number, optional): The quality of the image, between 0-100. Not applicable to PNG images, only used for JPEG format (default: 100)
• includeBase64 (boolean, optional): Include base64-encoded image data in the response (default: false)
• annotate (boolean, optional): Overlay numbered labels (1, 2, …) on elements from the session ref map; refs are built from the last ARIA snapshot or auto-taken if ref map is empty (default: false)
• annotateContent (boolean, optional): When true with annotate, include content elements (headings, list items, etc.) in the overlay; uses interactiveOnly: false when building refs for this screenshot (default: false)
• annotateCursorInteractive (boolean, optional): When true with annotate, also include cursor-interactive elements (clickable/focusable by CSS without ARIA role) in the overlay (default: false)

Returns:

• filePath (string): Full path of the saved screenshot file
• image (object, optional): Screenshot image data with mimeType (only included when includeBase64 is true)
• annotations (array, optional): When annotate is true, list of { ref, number, role, name, box } for each overlaid element; box coordinates are document-relative for fullPage, element-relative when selector is used

Notes:

• The screenshot is always saved to the file system and the file path is returned
• By default, image data is NOT included in the response to reduce payload size
• Set includeBase64 to true when the AI assistant cannot access the MCP server's file system (e.g., remote server, containerized environment, or different machine)
• The quality parameter only applies to JPEG images. PNG images are always saved at full quality
• Lower quality values (e.g., 50-70) result in smaller file sizes but reduced image quality
• Annotation uses the session ref map; use annotateContent to include headings/content, or annotateCursorInteractive to include CSS-clickable elements, without a prior ARIA snapshot with those options

Parameters:

• selector (string, optional): CSS selector to limit the HTML content to a specific container
• removeScripts (boolean, optional): Remove all script tags from the HTML (default: true)
• removeComments (boolean, optional): Remove all HTML comments (default: false)
• removeStyles (boolean, optional): Remove all style tags from the HTML (default: false)
• removeMeta (boolean, optional): Remove all meta tags from the HTML (default: false)
• cleanHtml (boolean, optional): Perform comprehensive HTML cleaning (default: false)
• minify (boolean, optional): Minify the HTML output (default: false)
• maxLength (number, optional): Maximum number of characters to return (default: 50000)

Returns:

• output (string): The requested HTML content of the page

Parameters:

• selector (string, optional): CSS selector to limit the text content to a specific container
• maxLength (number, optional): Maximum number of characters to return (default: 50000)

Returns:

• output (string): The requested text content of the page

Parameters:

• outputPath (string, optional): Directory path where PDF will be saved (default: OS temp directory)
• name (string, optional): PDF name (default: "page")
• format (enum, optional): Page format - "Letter", "Legal", "Tabloid", "Ledger", "A0" through "A6" (default: "A4")
• printBackground (boolean, optional): Whether to print background graphics (default: false)
• margin (object, optional): Page margins with top, right, bottom, left (default: "1cm" for each)

Returns:

• filePath (string): Full path of the saved PDF file

Parameters:

• outputDir (string, optional): Directory where the video file will be saved (default: OS temp directory)
• name (string, optional): Name for the video file without extension (default: "recording") Returns:
• message (string): Status message

Notes:

• Uses CDP screencast — works in all modes (headless, headed, persistent, CDP attach)
• Only supported on Chromium-based browsers
• Recording captures all page interactions until content_stop-recording is called

Returns:

• filePath (string, optional): Full path of the saved WebM video file

Notes:

• Must be called after content_start-recording
• The video is saved as a WebM file (VP8 codec)

Interaction Tools

Parameters:

• selector (string, required): Ref (e.g. e1, @e1, ref=e1), getByRole/getByLabel/getByText/getByPlaceholder/getByTitle/getByAltText/getByTestId expression, or CSS selector for the element to click
• timeoutMs (number, optional): Time to wait for the element in ms (default: 10000)
• waitForNavigation (boolean, optional): Wait for navigation triggered by click in parallel (race-free), then for network idle. Use when click opens a new page. Default: false
• waitForTimeoutMs (number, optional): Timeout for navigation and network idle wait in ms. Only when waitForNavigation is true. Default: 30000

Parameters:

• selector (string, required): Ref (e.g. e1, @e1), getByRole/getByLabel/getByPlaceholder expression, or CSS selector for the input field
• value (string, required): Value to fill
• timeoutMs (number, optional): Time to wait for the element in ms (default: 10000) </de