Browser Ref

MCP浏览器工具

提供方 未标注

浏览器工具 stdio · 本地进程 会话登录 社区 / 第三方 Claude DesktopClaudeCursorVS Code
查看接入方式

让你的 AI 代理使用你已有的 Chrome 或 Edge。每个页面都会变成一个带编号的 [eN] 快照,因此它通过引用进行点击,而不是依赖脆弱的 CSS 选择器,同时 shadow DOM 和跨源 iframe...

一句话选型结论

按资料字段整理

Browser Ref 属于浏览器工具类 MCP 服务器,stdio · 本地进程,会话登录,可直接接入 Claude Desktop、Claude、Cursor 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类浏览器工具 传输方式stdio · 本地进程 鉴权会话登录 部署方式本地部署
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

浏览器工具
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

网页抓取

安装与配置

stdio · 本地进程 会话登录
客户端在本机拉起子进程,数据不出本机
npx -y @lobehub/market-cli skills install zy2755-browser-ref-mcp-browser-control --agent claude-code

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js 等运行时,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
自动操作网页

打开页面、点击、填表,把浏览器动作交给模型执行。

抓取结构化数据

把页面内容整理成表格或 JSON,省掉手工复制粘贴。

关键流程回归

按步骤检查页面是否正常,回归时少漏环节。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好会话登录对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在浏览器工具场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Browser Ref当前 未标注 stdio · 本地进程 本地部署 有 2026-11-20
Playwright MCP Server 21 stdio · 本地进程 本地部署 有 2026-05-18
Fetch 9a2682de 1 SSE · 服务端推送 支持远程部署 有 2026-05-18
Browser 738d52bc 未标注 stdio · 本地进程 本地部署 有 2026-05-17
MCP 40600ece 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Skyvern MCP 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

浏览器工具
字段来自项目仓库与公开索引,中文说明由本站标注
提供方未标注上游标注的维护方 未标注
分类浏览器工具本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式会话登录远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-11-20上游最后核验时间

详细介绍

8.1 KB
来自项目仓库与上游目录的原文,未做删改

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

### LobeHub Skills marketplace```bash
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

  • punkpeye/awesome-mcp-servers — listed under "Web content access and automation"
  • mcpservers.org — directory listing with install and config walkthroughs
  • Glama — rated A for tool definitions, all 14 tools indexed
  • cursor.directory — Cursor plugin directory

Any other client```bash

npx -y browser-ref-mcp


Or add it to your client config:```json
{
  "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```bash
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:```json
{
  "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

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 `` 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:```bash
# 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:json "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


中文说明

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Browser Ref 怎么安装?

在客户端按下面的安装命令接入:npx -y @lobehub/market-cli skills install zy2755-browser-ref-mcp-browser-control --agent claude-code。装完在客户端配置里引用同一个包或端点。

Browser Ref 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Browser Ref 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Browser Ref 需要 API Key 吗?

资料标注需要会话登录认证,使用前准备好对应凭据,并按最小权限配置。

Browser Ref 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor、VS Code、Windsurf、Cline;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Browser Ref 能提供哪些能力?

资料显示能力标签包括 网页抓取。具体工具清单以官方文档为准。

Browser Ref 需要什么运行环境?

属于本地进程,需要在本机装好运行环境。

Browser Ref 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-11-20。