Browser DevTools MCP

0.6.9 verified Sat Apr 25 auth: no javascript

A Model Context Protocol (MCP) server that gives AI coding assistants comprehensive browser automation and debugging capabilities, including execution-level inspection (logs, network, console messages) and visual feedback (screenshots, ARIA snapshots, PDFs). Version 0.6.9 is the current stable release; the package is actively developed on GitHub. Supports both Browser (Playwright) and Node.js (Inspector Protocol) platforms with session management, design comparison (Figma), OpenTelemetry integration, and multiple transport modes (stdio, HTTP). Differentiates from generic browser automation tools by focusing on AI agent integration via MCP, providing structured debugging tools (tracepoints, logpoints) and visual snapshots for LLM-based workflows.

Common errors

error Error: Cannot find module 'browser-devtools-mcp' ↓

cause Package not installed or not resolved due to ESM/CJS mismatch

fix

npm install browser-devtools-mcp --save. Ensure project uses ESM (type: module in package.json) or use dynamic import if using CJS.

error TypeError: platform.getTools is not a function ↓

cause Platform instance not properly instantiated or wrong class imported

fix

Ensure you import the platform class from the correct subpath, e.g., import { BrowserPlatform } from 'browser-devtools-mcp/platforms/browser'.

error Error: Connection refused to Chrome DevTools Protocol endpoint ↓

cause Chrome/Chromium is not running or the debug port is not accessible

fix

For Node platform, start Node with --inspect flag. For browser platform, ensure Playwright browsers are installed: npx playwright install.

Warnings

gotcha Closed browser tab invalidates element references: after a tab is closed, previous element handles (from screenshots/snapshots) become stale. New tool calls will open a fresh tab, but all prior references must be re-fetched. ↓

fix After tab closure, take a new snapshot (e.g., takeScreenshot) before using any element references.

gotcha Session network-idle state resets on new tab: in-flight request tracking and network idle detection are reset when a tab is reopened. Long-running network operations may cause unexpected timeouts. ↓

fix Re-evaluate network state after tab recovery; avoid assumptions about pending requests.

deprecated Node platform connection via process name (e.g., '--name myapp') is deprecated. Use PID, port, or WebSocket URL instead. ↓

fix Use --pid <PID> or --port <PORT> flags instead of --name.

breaking v0.6.0 changed the signature of runServer() – first argument is now a options object ({ platform, transport, sessionTimeout }) instead of separate parameters. ↓

fix Update calls to runServer({ platform, transport: 'stdio', sessionTimeout: 300000 }).

Install

npm install browser-devtools-mcp

yarn add browser-devtools-mcp

pnpm add browser-devtools-mcp

Imports

runServer
wrong
```
const runServer = require('browser-devtools-mcp')
```
correct
```
import { runServer } from 'browser-devtools-mcp'
```
Package is ESM-only (type: module). runServer is the main entry point for programmatic usage.

createBrowserSession

wrong

import { createBrowserSession } from 'browser-devtools-mcp'

correct

import { createBrowserSession } from 'browser-devtools-mcp/session'

Session functions are exported from a subpath: 'browser-devtools-mcp/session'.

BrowserTool
wrong
```
import { BrowserTool } from 'browser-devtools-mcp'
```
correct
```
import { BrowserTool } from 'browser-devtools-mcp/tools'
```
Tool classes are exported from subpaths like 'browser-devtools-mcp/tools' or 'browser-devtools-mcp/node-tools'.

Quickstart

Shows programmatic instantiation of the Browser Platform and running the MCP server via runServer().

// Quickstart: run MCP server for Browser platform with stdio transport
import { runServer } from 'browser-devtools-mcp';
import { BrowserPlatform } from 'browser-devtools-mcp/platforms/browser';

const platform = new BrowserPlatform({
  headless: true,
  defaultViewport: { width: 1280, height: 720 },
});

runServer({
  platform,
  transport: 'stdio',
  sessionTimeout: 300000,
}).catch(console.error);