Skip to main content
Glama

browser-ref-mcp

npm LobeHub MCP Publish to npm license node

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 problem

What happens with most browser tools

What this server does

The agent can't click what it sees

Selectors go stale between snapshot and click, shadow DOM and cross-origin iframes are invisible, the agent retries blindly

Semantic snapshot with [eN] refs, shadow DOM and cross-origin iframes flattened into one tree, four-level resolution fallback

Sessions keep dying

Browser closed by hand, process crash, port conflict — and the agent is stuck until you restart everything

Resident 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.

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).

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


Related MCP server: ecobrowser MCP server

The 14 tools

Tool

What it does

browser_navigate(url)

Navigate — automatically returns an interactive-element snapshot

browser_snapshot

Semantic 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 <select> 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_screenshot

Screenshot — returns the image and writes it to disk

browser_evaluate(js)

Escape hatch: run JS in the page

browser_wait

Wait for a duration, text, element, URL change, or network idle

browser_tabs

Multi-tab: list / new / select / close

browser_get_info

Health state, tab list, restart count, last error

browser_close

Close 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 <dir> / --channels chrome,msedge / --executable <path> / --viewport 1440x900 / --start-url <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


中文说明

Available Tools

14 tools
browser_clickA

点击元素(优先用快照里的 ref)。自动等待可操作、自动重解析失效 ref、点击后自动附最新快照。特殊对话框会自动处理并上报。

Inputs: ref, text, button, selector, +3 more.

browser_closeA

关闭浏览器(launch 模式下整个浏览器退出,profile 登录态保留;connect 模式只断开连接)。下次工具调用会自动重启。

Inputs: no named parameters.

browser_evaluateA

逃生舱:在页面里执行 JS 并返回 JSON 可序列化结果。传函数字符串如 () => document.title 或 () => {...};带 ref 时在该元素上执行((el, ) => el.value)。

Inputs: js (required), ref.

browser_get_infoA

查询浏览器健康状态:模式、标签列表、重启次数、最近错误/对话框/下载。不会启动浏览器。

Inputs: no named parameters.

browser_hoverC

鼠标悬停到元素上(触发悬浮菜单/tooltip)。

Inputs: ref, selector, timeoutMs.

browser_navigateB

导航到 URL,返回后自动附带页面交互元素快照(带 [eN] ref 编号,可直接用于 click/type)。缺协议时自动补 https://。

Inputs: url (required), newTab, snapshot, timeoutMs.

browser_press_keyC

按下键盘按键,如 Enter / Tab / ArrowDown / "Control+a"。带 ref 时先聚焦该元素。

Inputs: key (required), ref.

browser_screenshotA

截屏并保存到本地,返回图片(供多模态查看)。可整页、可视区或单元素(ref)。

Inputs: ref, filename, fullPage.

browser_scrollB

滚动页面或指定滚动容器(带 ref 时滚动该容器)。方向 + 像素量。

Inputs: direction (required), ref, amount.

browser_select_optionB

在下拉框(select)中选中选项。values 可为 value 或可见 label,自动两轮匹配。

Inputs: values (required), ref, selector, timeoutMs.

browser_snapshotB

获取当前页面语义快照:交互元素带 [eN] ref 编号(iframe 内容已拍平)。支持 rootRef(只看某元素子树)、selector、filter:"interactive" 只看交互元素。

Inputs: filter, rootRef, selector, maxElements.

browser_tabsB

多标签管理:list 列出 / new 新建 / select 切换(按 list 显示的 index 或 id)/ close 关闭。

Inputs: action (required), id, url, index.

browser_typeB

向输入框输入文本(先清空再输入)。submit:true 时回车提交。适用于 input/textarea/contenteditable。

Inputs: text (required), ref, clear, submit, +2 more.

browser_waitA

等待条件成立:timeMs 固定时长 / text 文本出现 / selector 元素出现 / url 跳转 / idle 网络空闲。可组合。

Inputs: url, idle, text, timeMs, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 14 tools

    Disambiguation5/5

    Every tool targets a distinct action: navigate loads URLs, snapshot reads structure, wait blocks on conditions, and click/type/press_key/select_option/hover/scroll each map to a unique interaction primitive. The only mild overlap (navigate also returns a snapshot) is resolved by navigate requiring a URL, so an agent can always pick correctly. browser_evaluate is clearly labeled as an escape hatch rather than a duplicate of any other tool.

    Naming Consistency4/5

    All 14 tools share a consistent `browser_` prefix and snake_case, with most following a verb or verb_noun form (navigate, click, press_key, select_option, get_info). Minor deviations exist: `browser_tabs` is a noun with a mode argument, and several actions are bare verbs without an object, but the set remains highly predictable.

    Tool Count5/5

    14 tools is well-scoped for a browser automation server: one tool per core primitive (navigate, snapshot, wait, interact, screenshot, evaluate) plus tabs and lifecycle management. Nothing feels padded, and no obvious primitive is split into multiple redundant tools.

    Completeness4/5

    The surface covers the full browse-inspect-interact loop plus lifecycle, tabs, JS evaluation, and health diagnostics, which handles nearly all agent workflows. Gaps remain for history navigation (back/forward), file upload/download interaction, and drag-and-drop, though evaluate provides a viable workaround.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers