agent-browser-mcp
Use it as an AI-agent browser-control MCP server that drives your existing Chrome/Edge and exposes stable [eN] refs with automatic browser recovery.
Navigate URLs and get interactive-element snapshots automatically.
Snapshot pages semantically, including open shadow DOM and cross-origin iframe content flattened into one ref tree.
Click, type, press keys, select options, hover, and scroll by ref or fallback selector/text.
Take screenshots, run JavaScript via
browser_evaluate, and wait for time/text/selector/URL/network-idle conditions.Manage multiple tabs: list, create, select, and close.
Check browser health, restart count, tabs, and recent errors with
browser_get_info; close the browser while preserving login profile.Recover lazily after browser crashes/manual closure, restore tabs, clean up orphans, and use timeout guardrails.
Operate in launch mode with persistent logins or connect to an already-running browser over CDP.
Configure headless mode, profile, browser channels, executable, viewport, start URL, and dialog behavior.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@agent-browser-mcp Go to news.ycombinator.com and click the top story"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
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-mcpOne 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-mcpOr 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 buildThen 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.jsonCursor —
~/.cursor/mcp.json, or Settings → Features → MCPClaude Code —
claude mcp add, or the samemcpServersshape
Related MCP server: ecobrowser MCP server
The 14 tools
Tool | What it does |
| Navigate — automatically returns an interactive-element snapshot |
| Semantic snapshot. |
| Click by ref, returns a fresh snapshot. Stale refs are re-resolved automatically |
| Type into a field (clears first). |
| Key press, e.g. |
| Pick |
| Hover to reveal hover-only menus |
| Scroll the page, or a specific scroll container |
| Screenshot — returns the image and writes it to disk |
| Escape hatch: run JS in the page |
| Wait for a duration, text, element, URL change, or network idle |
| Multi-tab: |
| Health state, tab list, restart count, last error |
| 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:
Semantic snapshot — an in-page DOM walk (accessibility role + accessible name +
cursor: pointerheuristics) that pierces open shadow DOM and flattens cross-origin iframe content into a single tree.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.Resolution fallback chain —
cssPath→getByRoleexact →getByRolefuzzy →getByText. Anything that hits is validated before use.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_infoexposes 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:9223Configuration
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
executablePathunless you have to. Once it is set, thechannelsfallback 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/profileto 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
Available Tools
14 toolsbrowser_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_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
Scored across 14 tools
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.
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.
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.
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
Related MCP Connectors
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Browz hosted MCP (free public beta): let an AI app drive your own Browz browser profiles from anywhere. Connect https://mcp.gobrowz.com/mcp and sign in with your Browz account (OAuth) or an agent token. Each call is relayed to the Browz app on your computer, which must be online with Remote control on and have a hardware security chip (Mac Secure Enclave or TPM 2.0). 17 tools: profiles, tabs, navigate, snapshot, act, wait, screenshot. Cookies, downloads and stored sign-ins stay on your computer.
Cloud browsers for AI agents: saved logins, residential IPs, live human takeover, 57 browser tools.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables browser automation through the MCP protocol, allowing AI agents to control a real browser using accessibility snapshots and natural language commands.-
- AlicenseAqualityCmaintenanceEnables AI agents to control a browser via MCP with structured perception, verified actions, and self-healing capabilities.1314 npm1MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to operate an isolated local Chromium browser through MCP, with semantic snapshots, ref-based actions, search, research, crawling, and CDP access.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables browser automation through MCP with native Playwright operations, deterministic assertions, and natural-language grounded actions, structured extraction, and bounded agent workflows over live page elements.13Apache 2.0