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: Execute code in browser page context or in Node.js VM sandbox on the server
• Session Management: Long-lived, session-based debugging with automatic cleanup
• 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
• JavaScript Execution: Run arbitrary JavaScript in the connected Node process via run_js-in-node (CDP Runtime.evaluate)—use return to get output; async/await supported. Inspect process.memoryUsage(), call require() modules, read globals
• 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. With selector, 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

Interaction Tools

• Click: Click elements by CSS selector or snapshot ref (e.g. e1, @e1, ref=e1). Refs come from a11y_take-aria-snapshot and are valid until the next snapshot or navigation.
• Fill: Fill form inputs (selector or ref)
• Hover: Hover over elements (selector or ref)
• Press Key: Simulate keyboard input; optional selector or ref (e.g. e1, @e1) to focus an element before sending the key
• Select: Select dropdown options (selector or ref)
• Drag: Drag and drop operations (source and target as selector or ref)
• Scroll: Scroll the page viewport or specific scrollable elements with multiple modes (by, to, top, bottom, left, right); optional selector/ref 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 (includeSnapshot: true) returns an ARIA snapshot with refs (output, refs); set includeSnapshot: false for url/status/ok only. Use snapshotInteractiveOnly and snapshotCursorInteractive to control which elements get refs (same as a11y_take-aria-snapshot).
• Go Back: Navigate backward in history. Same snapshot/refs behavior as Go To when includeSnapshot is true.
• Go Forward: Navigate forward in history. Same snapshot/refs behavior as Go To when includeSnapshot is true.
• Reload: Reload the current page. Same snapshot/refs behavior as Go To when includeSnapshot is true.

Run Tools

• JS in Browser: Execute JavaScript code inside the active browser page (page context with access to window, document, DOM, and Web APIs)
• JS in Sandbox: Execute JavaScript code in a Node.js VM sandbox on the MCP server (with access to Playwright Page, console logging, and safe built-ins)

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 detailed request/response data, filtering by resource type, status code, and more
• 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

Synchronization Tools

• Wait for Network Idle: Wait until the page reaches a network-idle condition based on in-flight request count, 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). 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)
• Dompoint: Monitors DOM mutations (subtree-modified, attribute-modified, node-removed)
• Netpoint: Monitors network requests/responses matching a URL pattern

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)

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.

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):

{
  "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.

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.

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.

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.

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.

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

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 |

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
├── run                       # Script execution commands
│   └── js-in-node            # Run JavaScript in the connected Node process
└── debug                     # Debug commands
    ├── connect               # Connect to Node.js process (pid, processName, port, 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:

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               # Navigate backward
│   ├── go-forward            # Navigate 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-id          # Get current trace ID
│   ├── new-trace-id          # Generate new trace ID
│   └── set-trace-id          # Set trace ID
├── react                     # React debugging commands
│   ├── get-component-for-element
│   └── get-element-for-component
├── run                       # Script execution commands
│   ├── js-in-browser         # Run JS in browser
│   └── js-in-sandbox         # Run JS in sandbox
├── 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
├── debug                     # Non-blocking debugging commands
│   ├── put-tracepoint        # Set a tracepoint (captures call stack)
│   ├── remove-tracepoint     # Remove a tracepoint
│   ├── list-tracepoints      # List all tracepoints
│   ├── clear-tracepoints     # Clear all tracepoints
│   ├── put-logpoint          # Set a logpoint (evaluates expression)
│   ├── remove-logpoint       # Remove a logpoint
│   ├── list-logpoints        # List all logpoints
│   ├── clear-logpoints       # Clear all logpoints
│   ├── put-exceptionpoint    # Enable exception catching
│   ├── put-dompoint          # Set DOM mutation breakpoint
│   ├── remove-dompoint       # Remove a DOM breakpoint
│   ├── list-dompoints        # List all DOM breakpoints
│   ├── clear-dompoints       # Clear all DOM breakpoints
│   ├── put-netpoint          # Set network request breakpoint
│   ├── remove-netpoint       # Remove a network breakpoint
│   ├── list-netpoints        # List all network breakpoints
│   ├── clear-netpoints       # Clear all network breakpoints
│   ├── add-watch             # Add a watch expression
│   ├── remove-watch          # Remove a watch expression
│   ├── list-watches          # List all watch expressions
│   ├── clear-watches         # Clear all watch expressions
│   ├── get-tracepoint-snapshots      # Get tracepoint snapshots
│   ├── clear-tracepoint-snapshots    # Clear tracepoint snapshots
│   ├── get-logpoint-snapshots        # Get logpoint snapshots
│   ├── clear-logpoint-snapshots      # Clear logpoint snapshots
│   ├── get-exceptionpoint-snapshots  # Get exception snapshots
│   ├── clear-exceptionpoint-snapshots # Clear exception snapshots
│   ├── get-dompoint-snapshots        # Get DOM mutation snapshots
│   ├── clear-dompoint-snapshots      # Clear DOM snapshots
│   ├── get-netpoint-snapshots        # Get network snapshots
│   ├── clear-netpoint-snapshots      # Clear network snapshots
│   └── 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                        Navigate back in browser history
#     ...

# 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 | networkidle> (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_take-pdf - Generate a PDF of the current page

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

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 | | 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 | | 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) |

Node Platform Configuration

| Variable | Description | Default | |----------|-------------|---------| | 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 port 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 | |----------|-------------|---------| | 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_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", "console", or "none" | 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 |

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): 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

Interaction Tools

Parameters:

• selector (string, required): CSS selector or ref (e.g. e1, @e1) for the element to click
• timeoutMs (number, optional): Time to wait for the element in ms (default: 10000)

Parameters:

• selector (string, required): CSS selector or ref (e.g. e1, @e1) for the input field
• value (string, required): Value to fill
• timeoutMs (number, optional): Time to wait for the element in ms (default: 10000)

Parameters:

• selector (string, required): CSS selector or ref (e.g. e1, @e1) for the element to hover
• timeoutMs (number, optional): Time to wait for the element in ms (default: 10000)

Parameters:

• key (string, required): Key to press (e.g., "Enter", "Escape", "Tab")
• selector (string, optional): CSS selector or ref (e.g. e1, @e1) to focus before sending the key
• holdMs (number, optional): Duration in milliseconds to hold the key (repeat duration if repeat is true)
• repeat (boolean, optional, default: false): If true, simulates key auto-repeat by pressing repeatedly during holdMs
• repeatIntervalMs (number, optional, default: 50, min: 10): Interval between repeated key presses in ms (only when repeat is true)
• timeoutMs (number, optional): Time to wait for the element when selector is set, in ms (default: 10000)

Parameters:

• selector (string, required): CSS selector or ref (e.g. e1, @e1) for the select element
• value (string, required): Value to select
• timeoutMs (number, optional): Time to wait for the element in ms (default: 10000)

Parameters:

• sourceSelector (string, required): CSS selector or ref (e.g. e1, @e1) for the source element
• targetSelector (string, required): CSS selector or ref for the target element
• timeoutMs (number, optional): Time to wait for source and target elements in ms (default: 10000)

Parameters:

• mode (enum, optional): Scroll mode - "by" (relative delta), "to" (absolute position), "top", "bottom", "left", "right" (default: "by")
• selector (string, optional): CSS selector or ref (e.g. e1, @e1) for a scrollable container. If omitted, scrolls the document viewport
• dx (number, optional): Horizontal scroll delta in pixels (used when mode="by", default: 0)
• dy (number, optional): Vertical scroll delta in pixels (used when mode="by", default: 0)
• x (number, optional): Absolute horizontal scroll position in pixels (used when mode="to")
• y (number, optional): Absolute vertical scroll position in pixels (used when mode="to")
• behavior (enum, optional): Native scroll behavior - "auto" or "smooth" (default: "auto")

Returns:

• mode (string): The scroll mode used
• selector (string | null): The selector of the scroll container if provided; otherwise null (document viewport)
• behavior (string): The scroll behavior used
• before (object): Scroll metrics before the scroll action (x, y, scrollWidth, scrollHeight, clientWidth, clientHeight)
• after (object): Scroll metrics after the scroll action (x, y, scrollWidth, scrollHeight, clientWidth, clientHeight)
• canScrollX (boolean): Whether horizontal scrolling is possible
• canScrollY (boolean): Whether vertical scrolling is possible
• maxScrollX (number): Maximum horizontal scrollLeft
• maxScrollY (number): Maximum vertical scrollTop
• isAtLeft (boolean): Whether the scroll position is at the far left
• isAtRight (boolean): Whether the scroll position is at the far right
• isAtTop (boolean): Whether the scroll position is at the very top
• isAtBottom (boolean): Whether the scroll position is at the very bottom

Usage:

• Reveal content below the fold
• Jump to the top/bottom without knowing exact positions
• Bring elements into view before clicking
• Inspect lazy-loaded content that appears on scroll

Parameters:

• width (number, required): Target viewport width in CSS pixels (minimum: 200)
• height (number, required): Target viewport height in CSS pixels (minimum: 200)

Returns:

• requested (object): Requested viewport configuration (width, height)
• viewport (object): Viewport metrics observed inside the page after resizing:
  • innerWidth, innerHeight: window.innerWidth/innerHeight
  • outerWidth, outerHeight: window.outerWidth/outerHeight
  • devicePixelRatio: window.devicePixelRatio

Notes:

• This affects window.innerWidth/innerHeight, CSS media queries, layout, rendering, and screenshots
• This does NOT resize the OS-level browser window
• Runtime switching to viewport=null (binding to real window size) is not supported by Playwright
• If you need real window-driven responsive behavior, start the BrowserContext with viewport: null and use the window resize tool instead

Parameters:

• width (number, optional): Target window width in pixels (required when state="normal", minimum: 200)
• height (number, optional): Target window height in pixels (required when state="normal", minimum: 200)
• state (enum, optional): Target window state - "normal", "maximized", "minimized", or "fullscreen" (default: "normal")

Returns:

• requested (object): Requested window change parameters (width, height, state)
• before (object): Window bounds before resizing (windowId, state, left, top, width, height)
• after (object): Window bounds after resizing (windowId, state, left, top, width, height)
• viewport (object): Page viewport metrics after resizing (innerWidth, innerHeight, outerWidth, outerHeight, devicePixelRatio)

Notes:

• Works best on Chromium-based browsers (Chromium/Chrome/Edge)
• Especially useful in headful sessions when running with viewport emulation disabled (viewport: null)
• If Playwright viewport emulation is enabled (viewport is NOT null), resizing the OS window may not change page layout
• On non-Chromium browsers (Firefox/WebKit), CDP is not available and this tool will fail

Navigation Tools

Parameters:

• url (string, required): URL to navigate to (must include scheme)
• timeout (number, optional): Maximum operation time in milliseconds (default: 0 - no timeout)
• waitUntil (enum, optional): When to consider navigation succeeded - "load", "domcontentloaded", "networkidle", or "commit" (default: "load")
• includeSnapshot (boolean, optional): When true (default), take an ARIA snapshot with refs after navigation and include output and refs in the response; when false, only url/status/ok are returned.
• snapshotInteractiveOnly (boolean, optional): When includeSnapshot is true, if set, only interactive elements get refs (same as a11y_take-aria-snapshot).
• snapshotCursorInteractive (boolean, optional): When includeSnapshot is true, if set, also include cursor-interactive elements in refs (same as a11y_take-aria-snapshot).

Returns:

• url (string): Final URL after navigation
• status (number): HTTP status code
• statusText (string): HTTP status text
• ok (boolean): Whether navigation was successful (2xx status)
• output (string, optional): When includeSnapshot is true, ARIA snapshot text (page URL, title, YAML tree).
• refs (record, optional): When includeSnapshot is true, map of ref id (e1, e2, ...) to role/name/selector; use in interaction tools (e.g. click @e1).

Parameters: timeout, waitUntil, includeSnapshot (default true), snapshotInteractiveOnly, snapshotCursorInteractive — same semantics as navigation_go-to for snapshot/refs.

Returns: url, status, statusText, ok; when includeSnapshot is true also output and refs (ARIA snapshot with refs).

Parameters: timeout, waitUntil, includeSnapshot (default true), snapshotInteractiveOnly, snapshotCursorInteractive — same semantics as navigation_go-to for snapshot/refs.

Returns: url, status, statusText, ok; when includeSnapshot is true also output and refs (ARIA snapshot with refs).

Parameters:

• timeout (number, optional): Maximum operation time in milliseconds (default: 0 - no timeout)
• waitUntil (enum, optional): When to consider navigation succeeded - "load", "domcontentloaded", "networkidle", or "commit" (default: "load")
• includeSnapshot (boolean, optional): When true (default), take an ARIA snapshot with refs after reload and include output and refs; when false, only url/status/ok.
• snapshotInteractiveOnly (boolean, optional): When includeSnapshot is true, control which elements get refs (same as a11y_take-aria-snapshot).
• snapshotCursorInteractive (boolean, optional): When includeSnapshot is true, include cursor-interactive elements in refs (same as a11y_take-aria-snapshot).

Returns:

• url (string): Final URL after reload
• status (number): HTTP status code
• statusText (string): HTTP status text
• ok (boolean): Whether reload was successful (2xx status)
• output (string, optional): When includeSnapshot is true, ARIA snapshot text.
• refs (record, optional): When includeSnapshot is true, map of ref id to role/name/selector for use in interaction tools.

Run Tools

Parameters:

• script (string, required): JavaScript code to execute

Returns:

• result (any): Result of the evaluation. This value can be of any type, including primitives, arrays, or objects. It represents the direct return value of the JavaScript expression executed in the page context.

Notes:

• The code executes in the PAGE CONTEXT (real browser environment):
  • Has access to window, document, DOM, Web APIs
  • Can read/modify the page state
  • Runs with the same permissions as the loaded web page
• The code runs in an isolated execution context, but within the page
• No direct access to Node.js APIs
• Return value must be serializable

Typical use cases:

• Inspect or mutate DOM state
• Read client-side variables or framework internals
• Trigger browser-side logic
• Extract computed values directly from the page

Parameters:

• code (string, required): JavaScript code to run on the MCP server in a VM sandbox. The code is wrapped in an async IIFE, so await is allowed. Use return ... to return a value
• timeoutMs (number, optional): Max VM CPU time for synchronous execution in milliseconds (default: 5000, max: 30000)

Returns:

• result (any): Return value of the sandboxed code (best-effort JSON-safe). If user returns undefined but logs exist, returns { logs }. If error occurs, returns { error, logs }

Available bindings:

• page: Playwright Page (main interaction surface)
• console: captured logs (log/warn/error)
• sleep(ms): async helper

Safe built-ins:

• Math, JSON, Number, String, Boolean, Array, Object, Date, RegExp
• isFinite, isNaN, parseInt, parseFloat
• URL, URLSearchParams
• TextEncoder, TextDecoder
• structuredClone
• crypto.randomUUID()
• AbortController
• setTimeout / clearTimeout

NOT available:

• require, process, fs, Buffer
• globalThis

Notes:

• This runs on the MCP SERVER (not in the browser)
• This is NOT a security boundary. Intended for trusted automation logic
• The timeoutMs parameter limits synchronous execution time, but does not automatically time out awaited Promises

Parameters:

• script (string, required): JavaScript code to execute in the Node process. Use return to pass a value back (e.g. return process.memoryUsage();). Async/await is supported (e.g. return await fetch(url).then(r => r.json());).
• timeoutMs (number, optional): Max evaluation time in milliseconds (default: 5000, max: 30000)

Returns:

• result (any): The result of the evaluation. Can be primitives, arrays, or objects. Must be serializable (JSON-compatible).

Notes:

• Requires debug_connect first—must be connected to a Node.js process
• You must use return to get output (e.g. return 2+2;, return process.memoryUsage();). The script runs inside an async function.
• Async code supported: use await and return a Promise; the tool waits for it and returns the resolved value.
• Executes in the NODE PROCESS CONTEXT (real Node.js environment):
  • Has access to process, require, global, and all loaded modules
  • Can read/modify process state
  • Full Node.js APIs (fs, http, etc.)
• Execution blocks the Node event loop until the script (and any returned Promise) completes
• Long-running scripts will block the process; use short scripts
• Return value must be serializable

Typical use cases:

• Inspect process state: return process.memoryUsage();, return process.uptime();
• Call loaded modules: return require('os').loadavg();
• Read globals or cached data
• Async: return await someAsyncCall();

Observability (O11Y) Tools

Parameters:

• type (enum, optional): Filter by message level - "ERROR", "WARNING", "INFO", "DEBUG"
• search (string, optional): Text to search for in messages
• timestamp (number, optional): Start time filter (Unix epoch milliseconds)
• sequenceNumber (number, optional): Only return messages after this sequence number
• limit (object, optional): Limit results (default: last 100). Omit or set count: 0 for no limit.
  • count (number, default 100): Maximum number of messages; 0 = no limit
  • from (enum): "start" or "end" (default: "end")

Returns:

• messages (array): Array of console messages with type, text, location, timestamp, and sequence number

Parameters:

• resourceType (enum, optional): Filter by resource type (e.g., "document", "script", "stylesheet")
• status (object, optional): Filter by status code range
  • min (number): Minimum status code
  • max (number): Maximum status code
• ok (boolean, optional): Filter by success/failure (2xx = success)
• timestamp (number, optional): Start time filter (Unix epoch milliseconds)
• `s