Summary
Bridges Claude to your actual Chrome browser instead of spinning up headless instances. Installs as both an MCP server and Chrome extension that communicate over WebSocket. Exposes 18 tools covering snapshots (accessibility tree with element refs), screenshots, clicks, typing, scrolling, tab management, console logs, and network requests. The key advantage is it operates on your real browser sessions, so corporate SSO, existing cookies, and authenticated states just work. Ships with agent rules that teach the snapshot-first workflow. Useful when you need Claude to verify UI changes, debug live pages, or interact with apps that require real auth without Playwright setup overhead.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
real-browser-mcp
The missing piece in AI coding: your agent can now see your REAL browser.
You ship a fix. Your agent says "done, please verify." You alt-tab to Chrome, navigate to the page, log in, click around, find the bug.
Your agent just wrote the code. It could also verify it. It already has your browser open right there. It just can't see it.
Now it can.
Quick Start
Two parts:
- MCP server - runs on your machine, talks to your AI agent
- Chrome extension - sits in your browser, executes the commands
1. Add the MCP server
Cursor (one click):
Or add manually in Cursor Settings > MCP > "Add new MCP server":
{
"mcpServers": {
"real-browser": {
"command": "npx",
"args": ["-y", "real-browser-mcp"]
}
}
}
Claude Desktop, Windsurf, or other MCP clients
Claude Desktop: Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). Add the same JSON block.
Windsurf: Settings > MCP. Same config.
Any MCP-compatible client works.
2. Install the Chrome extension
Or load from source:
git clone https://github.com/ofershap/real-browser-mcp.git
- Open
chrome://extensionsand enable Developer mode (toggle in the top right) - Click Load unpacked and select the
extension/folder from the cloned repo
Click the Real Browser MCP icon in your toolbar.
Green dot = connected. Gray = waiting for server.
Done. Your agent can see your browser.
How Others Compare
| Real Browser MCP | Playwright MCP | Chrome DevTools MCP | |
|---|---|---|---|
| Uses your existing browser | Yes | No, launches new | Partial, needs debug port |
| Sessions and cookies | Already there | Fresh profile | Manual setup |
| Works behind corporate SSO | Yes | No | Depends |
| Setup | Extension + MCP config | Headless browser | Chrome with --remote-debugging-port |
🧠 Teach Your Agent
The agent can use all 18 tools out of the box, but it works better when it knows when and how to chain them. A config file teaches the right workflow - snapshot first, then act, then verify.
Run one command:
npx real-browser-mcp --setup cursor
This installs:
~/.cursor/rules/real-browser-mcp.mdc- teaches the snapshot-first workflow, how to handle dropdowns, when to use screenshots vs snapshots~/.cursor/commands/check-browser.md- adds/check-browserto your Cursor chat
After that, type /check-browser in any chat. Or just say "check the result in my browser" and the agent knows what to do.
Claude Code setup
npx real-browser-mcp --setup claude
Adds an AGENTS.md to your project root. Claude Code auto-discovers it.
See agent-config/ for manual installation or to customize the rules.
What It Can Do
18 tools. Grouped by purpose.
See
| Tool | What it does |
|---|---|
browser_snapshot | Accessibility tree with element refs. Compact mode (default) returns only interactive elements |
browser_screenshot | Capture what's on screen |
browser_text | Extract raw text from page or element |
browser_find | Query elements by CSS selector |
Interact
| Tool | What it does |
|---|---|
browser_click | Click by ref or CSS selector |
browser_click_text | Click by visible text. Works through React portals and overlays |
browser_type | Type into inputs and contenteditable fields |
browser_press_key | Key combos (Enter, Escape, Ctrl+A) |
browser_scroll | Scroll pages and virtual containers |
browser_hover | Trigger tooltips and dropdowns |
browser_select | Pick from native <select> dropdowns |
browser_wait | Wait for elements to appear or disappear |
Navigate
| Tool | What it does |
|---|---|
browser_navigate | Go to a URL in the active tab |
browser_tabs | List, create, close, or focus tabs |
Debug
| Tool | What it does |
|---|---|
browser_console | Console output (log, warn, error) |
browser_network | XHR/fetch requests with status codes |
browser_evaluate | Run JavaScript via Chrome DevTools Protocol |
browser_handle_dialog | Handle alert/confirm/prompt dialogs |
Configuration
| Env var | Default | What it does |
|---|---|---|
WS_PORT | 7225 | WebSocket port for extension connection |
Connection drops are handled automatically with exponential backoff (1s to 30s), ping/pong health checks every 10s, and per-tool timeouts (5s for clicks, 60s for navigation).
Multiple Chrome profiles
Run two server instances on different ports:
{
"mcpServers": {
"browser-work": {
"command": "npx", "args": ["-y", "real-browser-mcp"]
},
"browser-personal": {
"command": "npx", "args": ["-y", "real-browser-mcp"],
"env": { "WS_PORT": "9333" }
}
}
}
Update the port in each extension popup to match.
Architecture
Everything stays on your machine. The extension connects to the MCP server via WebSocket on localhost. No cloud, no proxy, nothing leaves your browser.
real-browser-mcp/
├── mcp-server/ MCP server (npm package, TypeScript)
│ └── src/tools/ One file per tool, registry pattern
├── extension/ Chrome extension (Manifest V3, plain JS)
│ ├── background.js Service worker, WebSocket client, tool handlers
│ ├── content.js Console capture
│ └── popup/ Connection status UI
├── agent-config/ Pre-built configs for Cursor + Claude Code
│ ├── cursor/ Rules and commands
│ ├── skills/ Browser automation skill
│ └── setup.mjs One-command installer
└── tests/ Bridge + registry tests
Stack: TypeScript (strict) · MCP SDK · WebSocket · Chrome Extension Manifest V3 · Vitest
Development
git clone https://github.com/ofershap/real-browser-mcp.git
cd real-browser-mcp
npm install
npm run build
npm test
| Command | What it does |
|---|---|
npm run build | Compile TypeScript |
npm run dev | Watch mode |
npm test | Run tests |
npm run typecheck | Type check without emitting |
npm run setup:cursor | Install Cursor rule + command |
FAQ
Does it work with my logged-in sessions?
That's the whole point. The extension runs inside your actual Chrome - same cookies, same sessions, same local storage. No re-authentication needed.
Does it send data anywhere?
No. The MCP server and extension talk over WebSocket on localhost. Nothing leaves your machine. There's no analytics, no telemetry, no cloud component. Privacy policy.
Which AI clients work?
Any MCP-compatible client. Cursor, Claude Desktop, Claude Code, Windsurf, Cline, and anything else that speaks the MCP protocol.
Can I use it with multiple Chrome profiles?
Yes. Run two MCP server instances on different ports. See Configuration for the setup.
How is this different from Playwright MCP or browser-use?
They launch a new browser instance from scratch - no state, no cookies, no sessions. You have to replay the full login flow every time. This connects to the browser you already have open with everything already loaded.
Contributing
Bug reports, feature requests, and PRs welcome. Open an issue first for larger changes.
Author
README built with README Builder
License
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Categories
Registryactive
Packagereal-browser-mcp
TransportSTDIO
UpdatedMar 10, 2026
