Prototype · Preview: every server in the official registry, synced every 30 minutes. Sign in with Google to write reviews.Prototype · updated every 30 min
PopNx MCPMCP servers for people who use AI · explained in plain words

Browser Ref MCP

by zy2755version 0.2.0i★ 1iRuns on your computerRepository ↗
Registry nameio.github.zy2755/browser-ref-mcp

How to install

What it does

Reliable browser-control MCP server for AI agents: click by ref, self-healing sessions.

  • Connects Runs on your computer
  • Account or key No key needed
  • Category Web & browsers

Use together with

Skills that teach the AI this kind of work; they work alongside this one

timesfm

TimesFM (Time Series Foundation Model) is a pretrained time-series foundation model developed by Google Research for time-series forecasting.

by google-research★ 35,6291 skills

Skill · How-to guide

Shadowbroker

Open-source intelligence for the global theater. Track everything from the corporate/private jets of the wealthy, and spy satellites, to seismic events in one unified interface. Hook an AI agent up to have it parse through data and find previously unseen correlations. The knowledge is available to…

by BigBodyCobain★ 11,6021 skills

Skill · How-to guide

google-maps-scraper

scrape data from Google Maps. Extracts data such as the name, address, phone number, website URL, rating, reviews number, latitude and longitude, reviews,email and more for each place

by gosom★ 8,2091 skills

Skill · How-to guide

Why it ranks here

Lists are ordered by a usage score (out of 100) built from these parts

Popularity4/80GitHub stars or weekly downloads: the larger counts 60, the smaller 20
Freshness12/12Full marks for a release or code change within 30 days
Still answering0/8The cloud endpoint answered at the last check
Usage score16/100

Quality: Passed 3/3 basic checks (shown, not used for ordering) · Momentum: No data yet (Used only on the Trending tab)

Install

Pick the AI app you use, then copy the settings.

Let your AI install it with one sentence

Please install Browser Ref MCP. Follow https://mcp.popnx.com/i/zy2755-browser-ref-mcp.md, show me the commands and wait for my OK before running them.

Paste it into an AI that can work on your computer (such as Claude Code or Cursor). It reads our steps, shows you the commands and waits for your OK. No key, no sign-up. · See the full text your AI reads

Passed 3/3 checks · Runs on your computer · ✓ Commands checked Nov 16, 2026

First: which AI do you use?

Pick your app and the steps appear below.

Works with Claude, with some setup first

Install Node.js on your computer first (one time) · Only the Claude desktop app (Windows or Mac), not the web or phone

Let AI install it

Copy this message into a Claude chat. The AI checks your computer, tells you which file it will change, and waits for your OK every time.

Please install the MCP server Browser Ref MCP for Claude on this computer, in this order: 1) Check Node.js with node -v. If it is missing, tell me to install it from https://nodejs.org/en/download; do not install it yourself. 2) Use only this config (already checked by PopNx MCP): { "mcpServers": { "browser-ref": { "command": "npx", "args": [ "-y", "browser-ref-mcp" ] } } } 3) Tell me the full path of the file you will change, or the command you will run, and wait for my OK. 4) No key is needed. 5) Do what we agreed, then check that the Browser Ref MCP tools really show up.

This message has no key in it. If a key is needed, the AI will ask you to paste it yourself into the file or the app’s field.

  1. Install Node.js (if you don’t have it)

    Already installed? Check first · Open Terminal, type this command and press Enter

    node -v
    • A version number such as v26.13.1 = installed, skip this step
    • "command not found" (on Windows: "is not recognized") = not installed yet, or installed but Terminal needs to be closed and reopened
    How to open Terminal

    Mac: press ⌘ + Space, type Terminal, press Enter

    Windows: open Start, type Windows PowerShell, then Open

    Not installed: Open the official download page, pick the LTS version and the click-through installer: .pkg on Mac · .msi on Windows. Double-click and follow it to the end. No curl command needed

    Open the Node.js download page ↗

    When it’s done, close Terminal, open it again and run the same command. You should see a version number: node -v

    Install once; it works for everything that needs Node.js

  2. Open the Claude desktop app’s settings file

    SettingsDeveloperEdit Config

  3. Paste these settings and save the file

    {
      "mcpServers": {
        "browser-ref": {
          "command": "npx",
          "args": [
            "-y",
            "browser-ref-mcp"
          ]
        }
      }
    }
  4. Quit Claude and open it again

  5. Try it

    Use Browser Ref MCP and tell me what you can do for me, then show me one thing

    ✓ If Claude says it is using Browser Ref MCP or shows a Browser Ref MCP tool in the answer, you are connected

4 optional setting(s) (works without them)

The command above works without these. Add them only if you want to change something, following the maker’s description.

  • BROWSER_MCP_CDP_URL Connect to a browser already running with a debug port, e.g. http://127.0.0.1:9222. Leave unset to launch your own Chrome/Edge.
  • BROWSER_MCP_HEADLESS Run without a visible browser window (default: headed, so the user can watch and take over).
  • BROWSER_MCP_PROFILE Browser profile directory, keeps logins across sessions (default: ~/.browser-mcp/profile).
  • BROWSER_MCP_CHANNELS Comma-separated browser channel fallback chain (default: chrome,msedge).

Descriptions are as written by the maker.

Menu names checked against Anthropic’s help page on Nov 11, 2026 · your screen may differ slightly by app version

ChatGPT cannot connect Browser Ref MCP yet

Browser Ref MCP runs on your computer, but ChatGPT can only connect servers that run on the web

What you can do instead

A · Use an app that can connect Browser Ref MCP

  • Install Node.js on your computer first (one time) · Only the Claude desktop app (Windows or Mac), not the web or phone
  • Install Node.js on your computer first (one time)
  • Install Node.js on your computer first (one time)
  • Install Node.js on your computer first (one time)

B · Others in Web & browsers that work with ChatGPT

Picked from the most used in the same category, only ones that connect by address with no key

Works with Claude Code, with some setup first

Install Node.js on your computer first (one time)

Let AI install it

Copy this message into a Claude Code chat. The AI checks your computer, tells you which file it will change, and waits for your OK every time.

Please install the MCP server Browser Ref MCP for Claude Code on this computer, in this order: 1) Check Node.js with node -v. If it is missing, tell me to install it from https://nodejs.org/en/download; do not install it yourself. 2) Use only this config (already checked by PopNx MCP): claude mcp add --scope user browser-ref -- npx -y browser-ref-mcp 3) Tell me the full path of the file you will change, or the command you will run, and wait for my OK. 4) No key is needed. 5) Do what we agreed, then check that the Browser Ref MCP tools really show up.

This message has no key in it. If a key is needed, the AI will ask you to paste it yourself into the file or the app’s field.

  1. Install Node.js (if you don’t have it)

    Already installed? Check first · Open Terminal, type this command and press Enter

    node -v
    • A version number such as v26.13.1 = installed, skip this step
    • "command not found" (on Windows: "is not recognized") = not installed yet, or installed but Terminal needs to be closed and reopened
    How to open Terminal

    Mac: press ⌘ + Space, type Terminal, press Enter

    Windows: open Start, type Windows PowerShell, then Open

    Not installed: Open the official download page, pick the LTS version and the click-through installer: .pkg on Mac · .msi on Windows. Double-click and follow it to the end. No curl command needed

    Open the Node.js download page ↗

    When it’s done, close Terminal, open it again and run the same command. You should see a version number: node -v

    Install once; it works for everything that needs Node.js

  2. Open Terminal

    Mac: press Command+Space and type Terminal · Windows: open PowerShell

  3. Paste this command and press Enter

    claude mcp add --scope user browser-ref -- npx -y browser-ref-mcp
  4. Type /mcp in Claude Code

    You should see Browser Ref MCP listed as connected

  5. Try it

    Use Browser Ref MCP and tell me what you can do for me, then show me one thing

    ✓ If Claude Code says it is using Browser Ref MCP or shows a Browser Ref MCP tool in the answer, you are connected

4 optional setting(s) (works without them)

The command above works without these. Add them only if you want to change something, following the maker’s description.

  • BROWSER_MCP_CDP_URL Connect to a browser already running with a debug port, e.g. http://127.0.0.1:9222. Leave unset to launch your own Chrome/Edge.
  • BROWSER_MCP_HEADLESS Run without a visible browser window (default: headed, so the user can watch and take over).
  • BROWSER_MCP_PROFILE Browser profile directory, keeps logins across sessions (default: ~/.browser-mcp/profile).
  • BROWSER_MCP_CHANNELS Comma-separated browser channel fallback chain (default: chrome,msedge).

Descriptions are as written by the maker.

Menu names checked against Anthropic’s help page on Nov 11, 2026 · your screen may differ slightly by app version

Works with Cursor, with some setup first

Install Node.js on your computer first (one time)

Let AI install it

Copy this message into a Cursor chat. The AI checks your computer, tells you which file it will change, and waits for your OK every time.

Please install the MCP server Browser Ref MCP for Cursor on this computer, in this order: 1) Check Node.js with node -v. If it is missing, tell me to install it from https://nodejs.org/en/download; do not install it yourself. 2) Use only this config (already checked by PopNx MCP): { "mcpServers": { "browser-ref": { "command": "npx", "args": [ "-y", "browser-ref-mcp" ] } } } 3) Tell me the full path of the file you will change, or the command you will run, and wait for my OK. 4) No key is needed. 5) Do what we agreed, then check that the Browser Ref MCP tools really show up.

This message has no key in it. If a key is needed, the AI will ask you to paste it yourself into the file or the app’s field.

  1. Install Node.js (if you don’t have it)

    Already installed? Check first · Open Terminal, type this command and press Enter

    node -v
    • A version number such as v26.13.1 = installed, skip this step
    • "command not found" (on Windows: "is not recognized") = not installed yet, or installed but Terminal needs to be closed and reopened
    How to open Terminal

    Mac: press ⌘ + Space, type Terminal, press Enter

    Windows: open Start, type Windows PowerShell, then Open

    Not installed: Open the official download page, pick the LTS version and the click-through installer: .pkg on Mac · .msi on Windows. Double-click and follow it to the end. No curl command needed

    Open the Node.js download page ↗

    When it’s done, close Terminal, open it again and run the same command. You should see a version number: node -v

    Install once; it works for everything that needs Node.js

  2. Click this button to open Cursor

    Open in Cursor

    Cursor asks you to confirm; click Install

  3. Open the AI chat in Cursor in Agent mode

  4. Try it

    Use Browser Ref MCP and tell me what you can do for me, then show me one thing

    ✓ If Cursor says it is using Browser Ref MCP or shows a Browser Ref MCP tool in the answer, you are connected

4 optional setting(s) (works without them)

The command above works without these. Add them only if you want to change something, following the maker’s description.

  • BROWSER_MCP_CDP_URL Connect to a browser already running with a debug port, e.g. http://127.0.0.1:9222. Leave unset to launch your own Chrome/Edge.
  • BROWSER_MCP_HEADLESS Run without a visible browser window (default: headed, so the user can watch and take over).
  • BROWSER_MCP_PROFILE Browser profile directory, keeps logins across sessions (default: ~/.browser-mcp/profile).
  • BROWSER_MCP_CHANNELS Comma-separated browser channel fallback chain (default: chrome,msedge).

Descriptions are as written by the maker.

Menu names checked against Cursor’s help page on Nov 11, 2026 · your screen may differ slightly by app version

Works with VS Code, with some setup first

Install Node.js on your computer first (one time)

Let AI install it

Copy this message into a VS Code chat. The AI checks your computer, tells you which file it will change, and waits for your OK every time.

Please install the MCP server Browser Ref MCP for VS Code on this computer, in this order: 1) Check Node.js with node -v. If it is missing, tell me to install it from https://nodejs.org/en/download; do not install it yourself. 2) Use only this config (already checked by PopNx MCP): { "servers": { "browser-ref": { "type": "stdio", "command": "npx", "args": [ "-y", "browser-ref-mcp" ] } } } 3) Tell me the full path of the file you will change, or the command you will run, and wait for my OK. 4) No key is needed. 5) Do what we agreed, then check that the Browser Ref MCP tools really show up.

This message has no key in it. If a key is needed, the AI will ask you to paste it yourself into the file or the app’s field.

  1. Install Node.js (if you don’t have it)

    Already installed? Check first · Open Terminal, type this command and press Enter

    node -v
    • A version number such as v26.13.1 = installed, skip this step
    • "command not found" (on Windows: "is not recognized") = not installed yet, or installed but Terminal needs to be closed and reopened
    How to open Terminal

    Mac: press ⌘ + Space, type Terminal, press Enter

    Windows: open Start, type Windows PowerShell, then Open

    Not installed: Open the official download page, pick the LTS version and the click-through installer: .pkg on Mac · .msi on Windows. Double-click and follow it to the end. No curl command needed

    Open the Node.js download page ↗

    When it’s done, close Terminal, open it again and run the same command. You should see a version number: node -v

    Install once; it works for everything that needs Node.js

  2. Click this button to open VS Code

    Open in VS Code

    VS Code asks you to confirm; click Install

  3. Open the AI chat in VS Code in Agent mode

  4. Try it

    Use Browser Ref MCP and tell me what you can do for me, then show me one thing

    ✓ If VS Code says it is using Browser Ref MCP or shows a Browser Ref MCP tool in the answer, you are connected

4 optional setting(s) (works without them)

The command above works without these. Add them only if you want to change something, following the maker’s description.

  • BROWSER_MCP_CDP_URL Connect to a browser already running with a debug port, e.g. http://127.0.0.1:9222. Leave unset to launch your own Chrome/Edge.
  • BROWSER_MCP_HEADLESS Run without a visible browser window (default: headed, so the user can watch and take over).
  • BROWSER_MCP_PROFILE Browser profile directory, keeps logins across sessions (default: ~/.browser-mcp/profile).
  • BROWSER_MCP_CHANNELS Comma-separated browser channel fallback chain (default: chrome,msedge).

Descriptions are as written by the maker.

Menu names checked against VS Code’s help page on Nov 11, 2026 · your screen may differ slightly by app version

Other apps that use MCP, such as Windsurf, Zed or Gemini CLI, each add servers differently. See how in the app list.

See every app that uses MCP →

JSON settings are under “For developers” below

Stuck? Ask people who use Browser Ref MCP💬 Discussion →
For developers: Terminal commands and JSON settings

Installed on your computer

Claude Code

claude mcp add --scope user browser-ref -- npx -y browser-ref-mcp

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "browser-ref": {
      "command": "npx",
      "args": [
        "-y",
        "browser-ref-mcp"
      ]
    }
  }
}

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "browser-ref": {
      "command": "npx",
      "args": [
        "-y",
        "browser-ref-mcp"
      ]
    }
  }
}

VS Code (mcp.json)

{
  "servers": {
    "browser-ref": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "browser-ref-mcp"
      ]
    }
  }
}

Values you fill in

  • BROWSER_MCP_CDP_URL env
    Connect to a browser already running with a debug port, e.g. http://127.0.0.1:9222. Leave unset to launch your own Chrome/Edge.
  • BROWSER_MCP_HEADLESS env
    Run without a visible browser window (default: headed, so the user can watch and take over).
  • BROWSER_MCP_PROFILE env
    Browser profile directory, keeps logins across sessions (default: ~/.browser-mcp/profile).
  • BROWSER_MCP_CHANNELS env
    Comma-separated browser channel fallback chain (default: chrome,msedge).

Descriptions are as written by the maker.

These settings are generated from the maker’s registry entry. If the README says otherwise, follow the README.

At a glance

Downloads per weeki
Not on npm/PyPI
Licencei
Apache-2.0
Connection
Runs on your computer
Latest versioni
0.2.0
Published to registryi
Nov 16, 2026
Code last changedi
Nov 17, 2026
Maker
zy2755
Packages
npm: browser-ref-mcp
Registry status
Active

Which apps can use it

Based on how this server connects and on each app’s own docs, checked Nov 10, 2026.

Run on your computer in

ClaudeGooseLM StudioMsty StudioCherry StudioCursorVS Code + GitHub CopilotVisual StudioWindsurf (Devin Desktop)ZedKiroClineContinueJetBrains AI AssistantClaude CodeCodex CLIGemini CLIOpenCodenodecodeWarpLibreChatRaycast

All apps, with pros and cons →

Related guides

What it can do

Runs on your computer; the tool list appears in your AI app after you install it.

Basic checksi

We check information anyone can see; we have not read the code. Checks that do not apply are left out of the count. · Checked Nov 19, 2026

  • ✓ Pass

    Maker matches the repo

    The registry name was verified with the GitHub account zy2755, which owns the repo

  • ✓ Pass

    Still maintained

    Code last changed 2 days ago

  • ✓ Pass

    Has a licence

    Uses Apache-2.0

  • – Not applicable

    Endpoint responds

    This one runs on your computer; there is no internet endpoint

  • – Not applicable

    Sign-in with OAuth

    Runs on your computer and uses local settings instead

  • … Not checked yet

    No hidden instructions in tool descriptions

    Runs on your computer; we can only read tool lists from internet endpoints

Published vulnerabilities (OSV.dev)

Not checked yet

What we check → · JSON

Makers: ask for a re-check or report wrong info
For makers: add a badge to your README

If you made this, paste this code into your README. The badge links back to this page.

[![Featured on PopNx MCP](https://mcp.popnx.com/badge/zy2755-browser-ref-mcp.svg)](https://mcp.popnx.com/en/servers/zy2755-browser-ref-mcp)

Discussion

Ask, share a tip or report that it does not work. Sorted by what people marked helpful.

No posts yet. Be the first to ask or share.

Posts here are written by users, not the PopNx team.

Sign in to post

User reviews

No reviews yet

Sign in to write a review

Compared with others in Web & browsersi

  • More stars than 78% of the other 1609 servers in this category
  • Published to the registry more recently than 91% of the other 1609 servers in this category
  • Basic checks equal to or better than 99% of the other 1609 servers in this category

Compared with every active server in this category in the registry. Stars count only when the publisher owns the repo.

Common questions

Is Browser Ref MCP safe?

It passed 3 of 3 applicable basic checks. We have not read the code. Before adding a key or token, see what access the server asks for and use a key with only the permissions you need.

What keys or codes does it need?

The registry does not list a required key, though some servers ask you to sign in on first use.

Does it run on my computer or in the cloud?

It runs on your computer. Your AI app starts it when needed, and data does not pass through the maker’s servers (unless it calls an online service itself).

Is it still maintained?

The GitHub repo last changed 2 days ago, and the latest version (0.2.0) reached the registry 3 days ago.

Which apps can use it?

Apps that support MCP, such as Claude Desktop, Claude Code, Cursor and VS Code. You also need Node.js on your computer.

What can I use instead?

In the same category: Browser Use, changedetection.io (official), Apify MCP Server, Pomerado, Actionbook

Similar alternatives

Same category, other makers, commands already checked. Official ones first, then by stars.

Reading a card:↓ Downloads per weeki★ GitHub starsiThree pillars: reviews · checks · usageiUpdated = latest version published to the registryi

Browser Use

Lets AI do web tasks for you, such as filling forms, searching and extracting data, in the maker’s cloud browsers or on your computer.

by browser-useWidely used↓ 1.7M/wk★ 121.4KUpdated 29 days ago

Computer or cloud✓ service owner · browser-use.com

Apify MCP Server

Extract data from any website with thousands of scrapers, crawlers, and automations on Apify Store ⚡

by apifyWidely used★ 16.9KUpdated 2 days ago

Runs in the cloud✓ service owner · apify.com

Pomerado

Connect your agents to any website. The cheaper, faster and more reliable alternative to browser use

by PomeradoGrowing★ 1.8KUpdated yesterday

Runs in the cloud✓ service owner · pomerado.ai

Actionbook

Let your AI agent operate any website through a real, logged-in browser session.

by actionbookGrowing★ 1.6KUpdated 31 days ago

Runs in the cloud✓ service owner · actionbook.app
Compared with similar ones
This one
Browser Ref MCP
Browser Usechangedetection.io (official)Apify MCP ServerPomeradoActionbook
Runs whereInstalls on your computerCloud or install on your computerRuns in the cloud, nothing to installRuns in the cloud, nothing to installRuns in the cloud, nothing to installRuns in the cloud, nothing to install
Needs a keyNoYesNoYesNoNo
Add with + in ClaudeNoYesNoNoNoNo
Basic checks3/35/53/34/44/44/4
LicenseApache-2.0MITApache-2.0MITMITApache-2.0
PriceNo cost listed in the registryNo cost listed in the registryNo cost listed in the registryNo cost listed in the registryNo cost listed in the registryNo cost listed in the registry

README from the maker

Open the README

Copied from the maker’s repo as written. PopNx MCP has not reviewed or endorsed it. HTML, images and scripts are removed. Links lead off this site.

browser-ref-mcp

A reliable browser-control MCP server for AI agents. Click by ref, not by brittle CSS selectors — and when the browser dies, the next call just brings it back.

Built for the two things that actually break agent-driven browsing:

The problemWhat happens with most browser toolsWhat this server does
The agent can't click what it seesSelectors go stale between snapshot and click, shadow DOM and cross-origin iframes are invisible, the agent retries blindlySemantic snapshot with [eN] refs, shadow DOM and cross-origin iframes flattened into one tree, four-level resolution fallback
Sessions keep dyingBrowser closed by hand, process crash, port conflict — and the agent is stuck until you restart everythingResident process, lazy restart on next call, tab session restored, orphan cleanup, timeout guardrails

No browser download. It drives the Chrome or Edge you already have, via playwright-core.

Works with Claude Code, Claude Desktop, Cursor, Cline, Codex CLI, Windsurf, OpenClaw, and any client that speaks stdio MCP.


Quick start

Claude Code
/plugin install browser-ref-mcp --marketplace zy2755/browser-ref-mcp

One line installs the server plus a short skill that tells Claude when to reach for the browser and what to do when a ref goes stale.

LobeHub Skills marketplace
npx -y @lobehub/market-cli skills install zy2755-browser-ref-mcp-browser-control --agent claude-code

Also listed as an MCP server at lobehub.com/mcp/zy2755-browser-ref-mcp.

Where else it's listed
Any other client
npx -y browser-ref-mcp

Or add it to your client config:

{

"mcpServers": { "browser-ref-mcp": { "command": "npx", "args": ["-y", "browser-ref-mcp"] } } }

Restart the client completely (on macOS quit from the menu bar — closing the window does not reload config).

Install from source instead

git clone https://github.com/zy2755/browser-ref-mcp.git

cd browser-ref-mcp npm install && npm run build

Then point command at node and args at the absolute path of dist/index.js — GUI apps often don't inherit your shell's working directory, so relative paths tend to fail:

{

"mcpServers": { "browser-ref-mcp": { "command": "node", "args": ["/absolute/path/to/browser-ref-mcp/dist/index.js"] } } }

Config file locations:

  • Claude Desktop — macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Cursor — ~/.cursor/mcp.json, or Settings → Features → MCP
  • Claude Code — claude mcp add, or the same mcpServers shape

The 14 tools

ToolWhat it does
browser_navigate(url)Navigate — automatically returns an interactive-element snapshot
browser_snapshotSemantic snapshot. filter: "interactive" for interactive elements only, rootRef to scope to one subtree
browser_click(ref)Click by ref, returns a fresh snapshot. Stale refs are re-resolved automatically
browser_type(ref, text)Type into a field (clears first). submit: true presses Enter
browser_press_key(key)Key press, e.g. Enter / Escape / Control+a
browser_select_option(ref, values)Pick options by value or label, two-pass match
browser_hover(ref)Hover to reveal hover-only menus
browser_scroll(direction, amount, ref?)Scroll the page, or a specific scroll container
browser_screenshotScreenshot — returns the image and writes it to disk
browser_evaluate(js)Escape hatch: run JS in the page
browser_waitWait for a duration, text, element, URL change, or network idle
browser_tabsMulti-tab: list / new / select / close
browser_get_infoHealth state, tab list, restart count, last error
browser_closeClose the browser (profile logins are kept)
Using refs

Every interactive element in a snapshot carries an [eN] label:

[e38] link "Sign in"

[e42] textbox "Email" [e51] button "Continue"

So the agent calls browser_click({ "ref": "e42" }) — no selector guessing, no DOM archaeology. Elements inside iframes are flattened into the same tree with the same numbering, including across origins.


How clicking actually works

Most "click by selector" failures come from the page changing between the moment the agent reads it and the moment it clicks. This server separates *reading* from *locating*:

  1. Semantic snapshot — an in-page DOM walk (accessibility role + accessible name + cursor: pointer heuristics) that pierces open shadow DOM and flattens cross-origin iframe content into a single tree.
  2. Ref → locator recipe — each ref stores both a CSS path (id-anchored + nth-of-type, unique within its frame) *and* a role+name semantic description.
  3. Resolution fallback chain — cssPath → getByRole exact → getByRole fuzzy → getByText. Anything that hits is validated before use.
  4. Never a dead end — if a ref is truly dead, the error message tells the agent what to do next (re-snapshot, or wait first) instead of leaving it stuck in a retry loop.

How reconnection works

  • Process model — the MCP server itself is a resident daemon (stdio clients hold it open). The browser launches over a CDP pipe, not a websocket port, so there are no port conflicts.
  • Lazy restart — a health check runs before every tool call (browser.isConnected()). If the browser was closed by hand or crashed, the next call relaunches it and restores all tabs, explicitly telling the agent that old refs are invalid.
  • Orphan cleanup — if a leftover process is holding the profile, it is killed by profile path before retrying.
  • Hang guardrails — every Playwright call is wrapped in withTimeout, so a frozen browser returns a timeout instead of hanging forever.
  • Full-chain logging — ~/.browser-mcp/logs/server-YYYYMMDD.log (2 MB rotation, 3 files kept). browser_get_info exposes the last error and restart count.

Browser modes

`launch` mode (default) — starts a dedicated Chrome with its profile at ~/.browser-mcp/profile. Logins persist across restarts. You sign in to a given site once in this profile.

`connect` mode — attach to an already-running browser that has a debugging port open; it is not killed on exit:

# start Chrome with a debugging port first

chrome.exe --remote-debugging-port=9222

node dist/index.js --connect # defaults to http://127.0.0.1:9222 node dist/index.js --cdp-url http://127.0.0.1:9223

Configuration

Precedence: CLI args > env vars (BROWSER_MCP_*) > ~/.browser-mcp/config.json > built-in defaults.

Common flags: --headless / --profile / --channels chrome,msedge / --executable / --viewport 1440x900 / --start-url / --dialogs accept|dismiss (default accept).

Append them after the package name:

"args": ["-y", "browser-ref-mcp", "--headless", "--channels", "msedge"]

Full list: npx -y browser-ref-mcp --help.

Don't set `executablePath` unless you have to. Once it is set, the channels fallback chain (chrome → msedge) is skipped and only that single candidate remains — which lowers robustness across machines.


Security notes

  • The dedicated profile holds live logins (cookies) — it *is* your browser identity. Never commit ~/.browser-mcp/profile to any repository.
  • Page dialogs are auto-accepted by default. The agent cannot handle CAPTCHAs or payment flows; those still need a human.
  • Logs may contain page URLs including query parameters — clean them up after debugging.

Roadmap

File upload, richer download management, request interception, cookie/storage management, PDF export, a CLI front end.

License

Apache-2.0


中文说明