Browser MCP — Feature Specification

Backend technical design: technical-spec.md

Overview

Browser MCP is a Model Context Protocol (MCP) server that gives AI agents full control over a Chrome browser. It connects to the user's real installed Chrome via the n8n Browser Bridge extension, using their actual profile, cookies, and login sessions.

The AI can navigate pages, click elements, fill forms, read page content, take screenshots, manage cookies and storage, and execute JavaScript — all through MCP tools.

---

Connection Model

Single Connection

One browser connection at a time. The connection is established explicitly via the browser_connect tool and torn down via browser_disconnect.

• No sessions — there is no session concept. The server either has an active connection or it doesn't.
• No modes — always connects to the user's real installed Chrome via the Browser Bridge extension.

Connection Flow

1. AI calls browser_connect
2. Server launches Playwright, which connects over CDP to the relay server
3. Relay server waits for the Browser Bridge extension to connect via WebSocket
4. Extension reports its registered (user-selected) tabs to the relay — debugger is not attached yet
5. Connection is ready — AI can use browser tools

Tabs are lazily activated: the debugger only attaches to a tab when the AI first interacts with it.

Multi-Tab

All eligible Chrome tabs are controlled simultaneously. The extension automatically tracks tab lifecycle (open/close) and reports changes to the relay server. Each tab gets a unique page ID that tools accept via the optional pageId parameter. Omitting pageId targets the active page.

The relay maintains a lightweight metadata cache (title, URL) for all known tabs. Playwright only sees a tab after it has been activated (debugger attached). Activation is lazy — triggered on first tool interaction with that tab. Agent-created tabs (via browser_tab_open) are eagerly activated.

---

Tools

All tools except browser_connect and browser_disconnect require an active connection. They accept an optional pageId parameter to target a specific tab; the default is the active page.

Session

Tab Management

Navigation

Interaction

Inspection

Wait

State

---

Element Targeting

Interaction and inspection tools that operate on specific elements accept a target which is one of:

• ref (preferred) — an element reference string from browser_snapshot. Refs are stable within a snapshot but become stale after navigation or DOM changes.
• selector — a CSS, text, role, or XPath selector as a fallback.

Using refs from a recent snapshot is preferred because they are unambiguous and resilient to CSS changes.

---

Configuration

Programmatic API

const { tools, connection } = createBrowserTools({
  defaultBrowser: 'chrome',   // 'chrome' | 'chromium' | 'brave' | 'edge'
  browsers: {                  // optional executable/profile overrides
    chrome: { executablePath: '/path/to/chrome' },
  },
});

CLI Flags

Environment Variables

All CLI flags can be set via N8N_MCP_BROWSER_ prefixed env vars:

• N8N_MCP_BROWSER_DEFAULT_BROWSER
• N8N_MCP_BROWSER_TRANSPORT

CLI flags take precedence over environment variables.

---

Prerequisites

1. Chrome (or another Chromium-based browser) installed
2. n8n Browser Bridge extension loaded in Chrome:
   • Open chrome://extensions
   • Enable Developer mode
   • Click "Load unpacked" and select the mcp-browser-extension directory

---

Non-Goals

• Multi-browser support (Firefox, Safari) — Chromium only via CDP
• Remote browser connections — local machine only
• Browser profile management — uses the user's existing profile
• Session persistence — connection is per-server-lifetime