io.github.serkan-ozal/browser-devtools-mcp

Official

by serkan-ozal

Playwright browser & Node.js MCP. ARIA refs, screenshots, ref-based interactions.

io.github.serkan-ozal/browser-devtools-mcp (MCP)

Playwright-based “browser & Node.js MCP” that provides tooling for interacting with a browser using ARIA references and screenshot-based workflows. The server is described as supporting “ARIA refs” and “ref-based interactions,” indicating automation that targets elements via ARIA-related references and can incorporate screenshots.

🛠️ Key Features

Playwright browser integration
Node.js MCP
ARIA refs
Screenshots
Ref-based interactions

🚀 Use Cases

Automate browser actions using ARIA-referenced elements
Perform interaction flows based on references
Capture or use screenshots during browser automation

⚡ Developer Benefits

Uses Playwright for browser control
Supports ARIA ref targeting and reference-driven interactions

⚠️ Limitations

Limited metadata available in the provided source (no tool count or additional capabilities listed)

Install

Configuration

Environment variables

PLATFORM

Platform: browser (default) or node for Node.js backend debugging.

PORT

Port for HTTP transport.

SESSION_IDLE_SECONDS

Idle session timeout (seconds).

SESSION_IDLE_CHECK_SECONDS

Interval for checking idle sessions (seconds).

SESSION_CLOSE_ON_SOCKET_CLOSE

Close session when socket closes.

CONSOLE_MESSAGES_BUFFER_SIZE

Maximum console messages to buffer.

HTTP_REQUESTS_BUFFER_SIZE

Maximum HTTP requests to buffer.

BROWSER_SERVER_INSTRUCTIONS_ENABLE

When true, include server instructions in MCP server info (browser platform). Default: true.

BROWSER_POLICY_UI_DEBUGGING_ENABLE

When true, include UI_DEBUGGING_POLICY in server policies (browser platform). Default: false.

BROWSER_HEADLESS_ENABLE

Run browser in headless mode.

BROWSER_PERSISTENT_ENABLE

Use persistent browser context (preserves cookies, localStorage, extensions).

BROWSER_CDP_ENDPOINT_URL

CDP attach: http(s) root or ws(s) URL. Resolves via /json/version, /json/list, or ws /devtools/browser (Chrome 136+). Mutually exclusive with BROWSER_PERSISTENT_ENABLE.

BROWSER_CDP_ENABLE

When true and no BROWSER_CDP_ENDPOINT_URL: probe 127.0.0.1:9222 then :9229 for CDP. Else use BROWSER_CDP_ENDPOINT_URL or default http://127.0.0.1:9222.

BROWSER_CDP_OPEN_INSPECT

On loopback CDP failure, if Chrome is running, open chrome://inspect/#remote-debugging. Default true. Set false to disable.

BROWSER_PERSISTENT_USER_DATA_DIR

Directory for persistent browser context user data.

BROWSER_USE_INSTALLED_ON_SYSTEM

Use system-installed Chrome browser instead of Playwright's bundled browser.

BROWSER_EXECUTABLE_PATH

Custom browser executable path.

BROWSER_CHROMIUM_SANDBOX

When false, launches Chromium with --no-sandbox. Required for Docker/Lambda/CI.

BROWSER_LAUNCH_ARGS

Extra Chromium launch args (comma-separated).

BROWSER_ALLOWED_DOMAINS

Comma-separated list of allowed hostnames. When set, all requests to non-matching hosts are aborted. Subdomains match automatically.

BROWSER_LOCALE

Browser locale (e.g., "en-US", "tr-TR").

OTEL_ENABLE

Enable OpenTelemetry integration.

OTEL_SERVICE_NAME

OpenTelemetry service name.

OTEL_SERVICE_VERSION

OpenTelemetry service version.

OTEL_ASSETS_DIR

Directory containing OpenTelemetry bundle files.

OTEL_INSTRUMENTATION_USER_INTERACTION_EVENTS

User interaction events to instrument (comma-separated, e.g., "click,submit").

OTEL_EXPORTER_TYPE

OpenTelemetry exporter type: "otlp/http", "console", or "none".

OTEL_EXPORTER_HTTP_URL

OpenTelemetry collector base URL (e.g., "http://localhost:4318").

OTEL_EXPORTER_HTTP_HEADERSsecret

OpenTelemetry exporter HTTP headers (comma-separated key=value pairs).

AWS_REGION

AWS region for Bedrock usage.

AWS_PROFILE

AWS profile name for Bedrock usage.

AMAZON_BEDROCK_ENABLE

Enable Amazon Bedrock usage.

AMAZON_BEDROCK_IMAGE_EMBED_MODEL_ID

Amazon Bedrock image embedding model ID.

AMAZON_BEDROCK_TEXT_EMBED_MODEL_ID

Amazon Bedrock text embedding model ID.

AMAZON_BEDROCK_VISION_MODEL_ID

Amazon Bedrock vision model ID.

FIGMA_ACCESS_TOKENsecret

Figma API access token for design comparison.

FIGMA_API_BASE_URL

Figma API base URL.

DAEMON_PORT

Daemon mode port (CLI).

DAEMON_SESSION_IDLE_SECONDS

Daemon mode idle session timeout (seconds).

DAEMON_SESSION_IDLE_CHECK_SECONDS

Daemon mode idle session check interval (seconds).

NODE_SERVER_INSTRUCTIONS_ENABLE

When true, include server instructions in MCP server info (node platform). Default: true.

NODE_POLICY_DEBUGGING_ENABLE

When true, include NODE_DEBUGGING_POLICY in server policies (node platform). Default: false.

NODE_INSPECTOR_HOST

Inspector host for debug_connect when MCP runs in Docker (e.g. host.docker.internal). Default: 127.0.0.1.

TOOL_OUTPUT_SCHEMA_DISABLE

When true, omit tool output schema from MCP tool registration (can reduce token usage for some clients).

AVAILABLE_TOOL_DOMAINS

Comma-separated tool domains to enable (e.g. navigation,interaction,a11y,scenario). Unset = all tools. Browser: a11y, content, debug, figma, interaction, navigation, o11y, react, scenario, run, stub, sync. Node: debug, run.

WORKING_DIR

Working directory for project-level config (.browser-devtools-mcp/). Default: process.cwd().

SEARCH_STRATEGY

Search strategy: SIMPLE (default, minisearch + stemmer) or FTS5 (better-sqlite3, optional dep).

SCENARIO_SEARCH_STRATEGY

Override SEARCH_STRATEGY for scenario search only.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "browser-devtools-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "browser-devtools-mcp@0.9.1"
      ],
      "env": {
        "PLATFORM": "<YOUR_PLATFORM>",
        "PORT": "<YOUR_PORT>",
        "SESSION_IDLE_SECONDS": "<YOUR_SESSION_IDLE_SECONDS>",
        "SESSION_IDLE_CHECK_SECONDS": "<YOUR_SESSION_IDLE_CHECK_SECONDS>",
        "SESSION_CLOSE_ON_SOCKET_CLOSE": "<YOUR_SESSION_CLOSE_ON_SOCKET_CLOSE>",
        "CONSOLE_MESSAGES_BUFFER_SIZE": "<YOUR_CONSOLE_MESSAGES_BUFFER_SIZE>",
        "HTTP_REQUESTS_BUFFER_SIZE": "<YOUR_HTTP_REQUESTS_BUFFER_SIZE>",
        "BROWSER_SERVER_INSTRUCTIONS_ENABLE": "<YOUR_BROWSER_SERVER_INSTRUCTIONS_ENABLE>",
        "BROWSER_POLICY_UI_DEBUGGING_ENABLE": "<YOUR_BROWSER_POLICY_UI_DEBUGGING_ENABLE>",
        "BROWSER_HEADLESS_ENABLE": "<YOUR_BROWSER_HEADLESS_ENABLE>",
        "BROWSER_PERSISTENT_ENABLE": "<YOUR_BROWSER_PERSISTENT_ENABLE>",
        "BROWSER_CDP_ENDPOINT_URL": "<YOUR_BROWSER_CDP_ENDPOINT_URL>",
        "BROWSER_CDP_ENABLE": "<YOUR_BROWSER_CDP_ENABLE>",
        "BROWSER_CDP_OPEN_INSPECT": "<YOUR_BROWSER_CDP_OPEN_INSPECT>",
        "BROWSER_PERSISTENT_USER_DATA_DIR": "<YOUR_BROWSER_PERSISTENT_USER_DATA_DIR>",
        "BROWSER_USE_INSTALLED_ON_SYSTEM": "<YOUR_BROWSER_USE_INSTALLED_ON_SYSTEM>",
        "BROWSER_EXECUTABLE_PATH": "<YOUR_BROWSER_EXECUTABLE_PATH>",
        "BROWSER_CHROMIUM_SANDBOX": "<YOUR_BROWSER_CHROMIUM_SANDBOX>",
        "BROWSER_LAUNCH_ARGS": "<YOUR_BROWSER_LAUNCH_ARGS>",
        "BROWSER_ALLOWED_DOMAINS": "<YOUR_BROWSER_ALLOWED_DOMAINS>",
        "BROWSER_LOCALE": "<YOUR_BROWSER_LOCALE>",
        "OTEL_ENABLE": "<YOUR_OTEL_ENABLE>",
        "OTEL_SERVICE_NAME": "<YOUR_OTEL_SERVICE_NAME>",
        "OTEL_SERVICE_VERSION": "<YOUR_OTEL_SERVICE_VERSION>",
        "OTEL_ASSETS_DIR": "<YOUR_OTEL_ASSETS_DIR>",
        "OTEL_INSTRUMENTATION_USER_INTERACTION_EVENTS": "<YOUR_OTEL_INSTRUMENTATION_USER_INTERACTION_EVENTS>",
        "OTEL_EXPORTER_TYPE": "<YOUR_OTEL_EXPORTER_TYPE>",
        "OTEL_EXPORTER_HTTP_URL": "<YOUR_OTEL_EXPORTER_HTTP_URL>",
        "OTEL_EXPORTER_HTTP_HEADERS": "<YOUR_OTEL_EXPORTER_HTTP_HEADERS>",
        "AWS_REGION": "<YOUR_AWS_REGION>",
        "AWS_PROFILE": "<YOUR_AWS_PROFILE>",
        "AMAZON_BEDROCK_ENABLE": "<YOUR_AMAZON_BEDROCK_ENABLE>",
        "AMAZON_BEDROCK_IMAGE_EMBED_MODEL_ID": "<YOUR_AMAZON_BEDROCK_IMAGE_EMBED_MODEL_ID>",
        "AMAZON_BEDROCK_TEXT_EMBED_MODEL_ID": "<YOUR_AMAZON_BEDROCK_TEXT_EMBED_MODEL_ID>",
        "AMAZON_BEDROCK_VISION_MODEL_ID": "<YOUR_AMAZON_BEDROCK_VISION_MODEL_ID>",
        "FIGMA_ACCESS_TOKEN": "<YOUR_FIGMA_ACCESS_TOKEN>",
        "FIGMA_API_BASE_URL": "<YOUR_FIGMA_API_BASE_URL>",
        "DAEMON_PORT": "<YOUR_DAEMON_PORT>",
        "DAEMON_SESSION_IDLE_SECONDS": "<YOUR_DAEMON_SESSION_IDLE_SECONDS>",
        "DAEMON_SESSION_IDLE_CHECK_SECONDS": "<YOUR_DAEMON_SESSION_IDLE_CHECK_SECONDS>",
        "NODE_SERVER_INSTRUCTIONS_ENABLE": "<YOUR_NODE_SERVER_INSTRUCTIONS_ENABLE>",
        "NODE_POLICY_DEBUGGING_ENABLE": "<YOUR_NODE_POLICY_DEBUGGING_ENABLE>",
        "NODE_INSPECTOR_HOST": "<YOUR_NODE_INSPECTOR_HOST>",
        "TOOL_OUTPUT_SCHEMA_DISABLE": "<YOUR_TOOL_OUTPUT_SCHEMA_DISABLE>",
        "AVAILABLE_TOOL_DOMAINS": "<YOUR_AVAILABLE_TOOL_DOMAINS>",
        "WORKING_DIR": "<YOUR_WORKING_DIR>",
        "SEARCH_STRATEGY": "<YOUR_SEARCH_STRATEGY>",
        "SCENARIO_SEARCH_STRATEGY": "<YOUR_SCENARIO_SEARCH_STRATEGY>"
      }
    }
  }
}