![\"Browser](\"https://browser-devtools.com/assets/icons/icon.svg\"){kind=icon}
\n \n Browser DevTools MCP\n
\n \n
\n Browser DevTools MCP\n
\n ![\"NPM](\"https://badge.fury.io/js/browser-devtools-mcp.svg\"){kind=icon}
\n ![\"License\"](\"https://img.shields.io/badge/license-Elastic--2.0-blue\"){kind=icon}
\nA powerful Model Context Protocol (MCP) server that provides AI coding assistants with comprehensive automation and debugging capabilities across multiple platforms. This server enables both execution-level debugging (logs, network requests) and visual debugging (screenshots, accessibility snapshots) to help AI assistants understand and interact with applications effectively.\n
\n\n## Overview\n\nBrowser 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.\n\n### Supported Platforms\n\n| Platform | Description | Status |\n|----------|-------------|--------|\n| **Browser** | Playwright-powered browser automation with full DevTools integration | ✅ Available |\n| **Node** | Non-blocking debugging for Node.js backend processes via Inspector Protocol | ✅ Available |\n| **Backend** | Runtime- and language-agnostic backend verification (HTTP / gRPC / GraphQL / WebSocket) + log capture (file / docker / kubernetes) + database verification (Postgres / MySQL / SQLite) | ✅ Available |\n\nThe **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.\n\nThe **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.\n\nThe **Backend Platform** binds to wire protocols, not specific frameworks: agents drive backend services via HTTP/1.1, HTTP/2, gRPC (unary + 3 streaming modes), GraphQL, and stateful WebSockets, with automatic W3C trace propagation so every request becomes a verifiable correlation root. Paired with the `log_*` domain, agents capture server-side log lines (from files, docker containers, or kubernetes pods) for the same trace; paired with the `db_*` domain, agents inspect database state directly (schema discovery, parameterized reads, before-vs-after snapshot diffs, polling change feeds) against Postgres / MySQL / SQLite — closing the \"trigger and verify\" loop without locking in to any framework, language, or runtime.\n\n### Platform Selection\n\nChoose the platform by running the appropriate MCP server or CLI:\n\n| Use Case | MCP Server | CLI |\n|----------|------------|-----|\n| Browser automation & debugging | `browser-devtools-mcp` | `browser-devtools-cli` |\n| Node.js backend debugging | `node-devtools-mcp` | `node-devtools-cli` |\n| Backend verification (HTTP/gRPC/GraphQL/WS) + log capture + database (Postgres/MySQL/SQLite) | `backend-devtools-mcp` | `backend-devtools-cli` |\n\n### Browser Platform Capabilities\n\n- **Visual Inspection**: Screenshots, ARIA snapshots, HTML/text extraction, PDF generation\n- **Design Comparison**: Compare live page UI against Figma designs with similarity scoring\n- **DOM & Code-Level Debugging**: Element inspection, computed styles, accessibility data\n- **Browser Automation**: Navigation, input, clicking, scrolling, viewport control\n- **Execution Monitoring**: Console message capture, HTTP request/response tracking\n- **OpenTelemetry Integration**: Automatic trace injection into web pages, UI trace collection, and backend trace correlation via trace context propagation\n- **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\n- **Session Management**: Long-lived, session-based debugging with automatic cleanup\n- **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.\n- **Multiple Transport Modes**: Supports both stdio and HTTP transports\n\n### Node Platform Capabilities\n\n- **Connection**: Connect to Node.js processes by PID, process name, port, WebSocket URL, or Docker container\n- **Non-Blocking Debugging**: Tracepoints, logpoints, exceptionpoints without pausing execution\n- **Source Map Support**: Resolves bundled/minified code to original source locations; `debug_resolve-source-location` translates stack traces and bundle locations to original source\n- **OpenTelemetry Integration**: When the Node process uses `@opentelemetry/api`, tracepoint/logpoint snapshots automatically include `traceContext` (traceId, spanId) for correlating backend traces with browser traces\n- **Docker Support**: Connect to Node.js processes running inside Docker containers (`containerId` / `containerName`)\n\n### Backend Platform Capabilities\n\n- **Protocol Coverage**: HTTP/1.1 + HTTP/2 (via ALPN auto-negotiation, TLS), gRPC (unary + 3 streaming modes; .proto file or descriptor), GraphQL (query/mutation, persisted queries), and stateful multi-tool WebSocket (open / send / receive / close / list)\n- **Trace Propagation**: Every request auto-injects W3C `traceparent` so the resulting `traceId` chains into log/log_read for verification — turns the platform into a true \"trigger and verify\" loop, not just an HTTP client. Session-pinned trace context via `o11y_new-trace-id` / `o11y_set-trace-context` / `o11y_get-trace-context` lets the agent anchor a multi-tool flow to one trace without per-call plumbing; the pin is silently shadowed by an MCP-client-supplied `_metadata.traceId` so the orchestrator's correlation boundary stays intact\n- **Cookie Jar**: Session-scoped, RFC 6265 host/path scoped, auto-populated from `Set-Cookie`; agent-writable via `request_set-cookies` / `request_list-cookies` / `request_clear-cookies`\n- **Default Headers / Metadata**: Host-scoped HTTP default headers and target-scoped gRPC default metadata (`request_set-default-headers`, `request_set-default-metadata`) — auth tokens stay pinned to their host/target\n- **Replay**: Replay a captured curl command or HAR entry verbatim via `request_replay`\n- **Log Capture (file / docker / kubernetes)**: Register a log source by name (`log_register-source`), point-in-time read (`log_read`) or live stream (`log_follow` → `log_get-followed` → `log_stop-follow`), and merge across multiple sources chronologically (`log_read-multi`)\n- **Log Pipeline**: `tail` / `since` / `until` / substring `pattern` / heuristic `level` / `parseJson` + dot-path `jsonFilter` / `coalesce` for multi-line stack traces / `contextBefore` + `contextAfter` for grep-style windows / `select` for JSONL projection — all composable on a single read call\n- **Rotation-Aware Following**: File source survives logrotate's rename-and-recreate, copy-and-truncate, and in-place truncate without `fs.watch` — deterministic cross-platform behavior (Linux/macOS/Windows/NFS/container FS)\n- **Auto-Redaction**: Returned log lines have Authorization / Cookie / X-API-Key headers, Bearer/Basic tokens, `password=` / `token=` / `api_key=` pairs, `*_SECRET` / `*_TOKEN` env-style assignments, and matching JSON keys redacted before reaching the agent — credentials never reach the LLM context window (`BACKEND_LOG_REDACT_ENABLE` toggle, default on)\n- **Source Liveness Probe**: `log_check-source` reports `{ reachable, sizeBytes, lastModified, recentLineCount, error }` for fast \"why is log_read returning empty\" diagnostics\n- **Database Verification (Postgres / MySQL / SQLite)**: Open named connections (`db_connect` with `connectionStringEnv` so secrets stay in `process.env`, never in the agent's context), discover schema (`db_list-tables`, `db_describe-table` returns columns + primary key + indexes + foreign keys + row count estimate), run parameterized reads (`db_query`), and inspect state across protocol calls — paired with `request_*` this lets agents assert \"the POST actually created the row with these values\"\n- **Snapshot & Diff State Verification**: `db_snapshot` captures a point-in-time set of rows keyed by primary key; two snapshots fed to `db_diff` yield exact `added` / `removed` / `changed` (with `changedColumns`) — the canonical before/after assertion primitive for AI-agent verification\n- **Polling Change Feed**: `db_watch-changes` + `db_get-changes` stream diffs into a ring buffer at configurable cadence — agent watches `audit_logs` (or any table), triggers the request, drains the buffer to see exactly which rows the system wrote async\n- **Readonly Defense-in-Depth**: Connections open in server-side READ ONLY mode by default (Postgres `default_transaction_read_only`, MySQL `SESSION TRANSACTION READ ONLY`, SQLite OS-level readonly file) — the actual security boundary, independent of the SQL parser whitelist that fast-fails write keywords. Writes flow only through `db_transaction-begin({ writable: true })` on connections explicitly opened with `allowWrites:true`, plus `db_seed` (structured row INSERTs) and `db_run-script` (raw multi-statement DDL/fixtures)\n- **Column-Aware Redaction**: Result-set columns matching `BACKEND_DB_QUERY_REDACT_KEYS` (default `password`, `token`, `api_key`, `password_hash`, …) are replaced with `[REDACTED]` before reaching the agent; redaction recurses into JSON/JSONB column values too — `users.metadata.api_key` is caught without explicit configuration\n- **Optional Peer Deps**: Engine drivers (`pg`, `mysql2`, `better-sqlite3`) are loaded only when actually used — install only what your verification scenarios need\n\n## Browser Platform Features\n\n### Content Tools\n- **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.\n- **HTML/Text Extraction**: Get page content with filtering, cleaning, and minification options\n- **PDF Export**: Save pages as PDF documents with customizable format and margins\n- **Video Recording**: Record browser page interactions as WebM video using Playwright's native `page.screencast` API (1.59+). Start with `content_start-recording`, stop with `content_stop-recording`. Works in all modes (headless, headed, persistent, CDP attach).\n\n### Interaction Tools\n- **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('demo@example.com')`, `getByTitle('…')`, `getByAltText('…')`, `getByTestId('…')`), or CSS selector. Refs come from `a11y_take-aria-snapshot` and are valid until the next snapshot or navigation.\n- **Fill**: Fill form inputs (ref, getByRole/getByLabel/getByPlaceholder/etc., or CSS selector)\n- **Hover**: Hover over elements (ref, getByXYZ expression, or CSS selector)\n- **Press Key**: Simulate keyboard input; optional ref, getByXYZ expression, or CSS selector to focus an element before sending the key\n- **Select**: Select dropdown options (ref, getByRole/getByTestId/etc., or CSS selector)\n- **Drag**: Drag and drop (source and target as ref, getByXYZ expression, or CSS selector)\n- **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\n- **Resize Viewport**: Resize the page viewport using Playwright viewport emulation\n- **Resize Window**: Resize the real browser window (OS-level) using Chrome DevTools Protocol\n\n### Navigation Tools\n- **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).\n- **Go Back / Go Forward**: Navigate backward or forward in history. Same **waitForNavigation** (default true), **waitForTimeoutMs**, snapshot/refs and optional screenshot behavior as Go To.\n- **Reload**: Reload the current page. Same **waitForNavigation** (default true), **waitForTimeoutMs**, snapshot/refs and optional screenshot behavior as Go To.\n\n### Execute tool (batch)\n- **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-