Z
zy2755/browser-ref-mcp
A reliable browser-control MCP server for AI agents.
★ 1·updated 2026-11-17
View on GitHub ↗Direct link · no redirect page
We have no copy-paste install command and no public remote endpoint, so we do not print a config. The step above is reference only, not a command we can vouch for. A made-up one is worse than none. How each client wires MCP up →
- Star count
- 1 ★ · zy2755/browser-ref-mcp · read from the GitHub search API · (checked 2026-11-19 20:00:48)
- Source
- collected from the punkpeye/awesome-mcp-servers list · type: MCP server
- Harvest history
- first seen 2026-11-18 · last seen 2026-11-20 · seen 3× · listed by 3 sources
- Score
- score 300 · 1 ★ · 3 sources · mcp
FAQ (answers come from our records)
Who is it for?
We filed it under these tags: MCP servers. The tags come from the entry itself, not a taxonomy we imposed.
Who maintains it?
repository
zy2755/browser-ref-mcp;first catalogued 2026-11-18;last seen 2026-11-20。There is no official certification or quality rating here — we record sources and dates only.README excerpt (English, untranslated) · Read the full README on GitHub →
# browser-ref-mcp
Excerpted from the repository README (abridged)
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 |
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 |
Listed badge (optional)
Copy this line into the README if you want the listing mark. Optional, and it does not affect being listed.
[](https://anclum.com/en/s/zy2755-browser-ref-mcp/)
- Source
- awesome · https://github.com/zy2755/browser-ref-mcp
- Browse by field
- MCP servers
- Traction
- 1 ★
- Listed by
- 3 independent sources
- added
- today
More MCP servers
Filed under
Every tag opens the full list for that filter. Counts are the live catalogue figures.