Everyone is building "agentic browsers." Most of them hand the agent a new browser: headless Chromium, a cloud VM, a clean profile with no cookies.
That is the wrong tool for the coding loop.
You ship a fix. The agent says "done, please verify."
You already have Chrome open on staging, past SSO, on the exact page that breaks.
The agent wrote the code. It could verify it there. It just cannot see that browser.
real-browser-mcp is the bridge: a local MCP server plus a Chrome extension over localhost WebSocket. Your agent talks MCP. Your real Chrome executes. Sessions stay on your machine.
MCP server + Chrome extension for AI browser control with real sessions.
MIT
마지막 확인
2026-11-16
스타
59
도구
—
가동 시간
—
This is not Playwright with a fresh profile. Not a hosted agent browser. Not CDP remote-debugging bolted onto your default Chrome profile (Chrome 136+ blocks that path for good security reasons).
Quick Start
Two parts:
MCP server - runs on your machine, talks to your AI agent (Cursor, Claude Code, VS Code, …)
Chrome extension - runs inside your real Chrome and executes the tools
1. Add the MCP server
Cursor (one click):
Or add manually in Cursor Settings > MCP > "Add new MCP server":
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.
Open chrome://extensions and 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.
Agent Plugins
This repo ships as an Agent Plugins1.0.0 package: root plugin.json, mcp.json, and skills/real-browser-control/ teach agents when to pick real Chrome over headless / cloud agentic browsers.
Claude Code .claude-plugin/ and agent-config/ remain for rules and marketplace flows. Agent Plugins is the cross-client layout (MCP + skill in one tree).
Cursor (local plugin): clone the repo, then copy or symlink it to ~/.cursor/plugins/local/real-browser-mcp and reload the window. You still need the Chrome extension connected. One-click MCP install below adds only the server unless you also install the local plugin folder.
Chrome 136+ refuses --remote-debugging-port on the default profile, so everyday logged-in Chrome is hard to attach without a throwaway profile
Real Browser MCP
Your Chrome via MV3 extension + localhost MCP
Not for CI parallel clean runs (use Playwright there)
If you want repeatable automation in CI, use Playwright. If you want the agent inside the browser you already authenticated, use this.
How Others Compare
Real Browser MCP
Playwright MCP
Chrome DevTools MCP
Cloud agentic browser
Browser
Your real Chrome
Launches new Chromium (usually)
Attach via CDP
Hosted / remote
Cookies / SSO already there
Yes
No (inject or replay)
Fragile on default profile after Chrome 136
Separate session
Connection model
Extension ↔ localhost WebSocket
Playwright driver
Remote debugging / autoConnect
Vendor cloud
Best fit
Live verify in IDE
CI + repeatable runs
Performance / DevTools debugging
Unattended remote browse
Leaves your machine?
No control plane
Local (unless you add cloud)
Local
Yes
🧠 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-browser to 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.
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).
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
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
Is this an agentic browser?
No. An agentic browser usually means the agent owns a new browser (local headless or cloud). real-browser-mcp connects an MCP agent to your existing Chrome. Same profile, same tabs, same logins.
Is the Chrome extension required?
Yes. The MCP server alone cannot see or control Chrome. Install the Chrome extension, open the popup, and wait for a green connected state before calling tools.
Does it work with my existing logins and corporate SSO?
Yes. The extension runs in your normal Chrome profile with cookies, sessions, and local storage. That is the point: verify against the session you already set up, including SSO you completed manually.
How is this different from Playwright MCP or browser-use?
Those stacks are built around a browser the automation tool launches (great for CI and clean repeats). Real Browser MCP is built around the browser you already have open. Use Playwright when you need deterministic runs. Use this when you need live session state.
How is this different from Chrome DevTools MCP?
Chrome DevTools MCP is excellent for DevTools-style debugging and can attach via CDP / autoConnect. After Chrome 136, remote debugging on the default user profile is blocked, which is exactly the profile that holds your real logins. Real Browser MCP uses an extension bridge over localhost WebSocket instead of opening a debug port on that profile.
Why not a cloud agentic browser?
Cloud browsers are remote machines. You re-auth, you leave the local IDE loop, and session data sits on someone else's infra. This project keeps control on localhost: MCP server ↔ extension. Page content still enters your AI client when tools return it; there is just no vendor browser SaaS in the middle.
Agent Plugins vs MCP-only install?
MCP-only (Cursor deeplink or mcp.json) registers the server and tools. The Agent Plugins package adds plugin.json and the real-browser-control skill so agents know when to prefer real Chrome over headless. Same npm server either way.
Is it safe to let an agent control my real browser?
The server and extension talk over WebSocket on localhost only; nothing is sent to a cloud control plane. The agent can still click, type, and read whatever is visible in the connected tab, including logged-in apps. Use a dedicated profile or tab when testing untrusted sites, and do not point automation at tabs with sensitive data unless you accept that risk.
No. The MCP server and extension talk over WebSocket on localhost. Nothing leaves your machine. There is no analytics, no telemetry, and no cloud component. Privacy policy.
Any MCP-compatible client. Cursor, Claude Desktop, Claude Code, Windsurf, Cline, and anything else that speaks the MCP protocol.
Yes. Run two MCP server instances on different ports. See Configuration for the setup.
Contributing
Bug reports, feature requests, and PRs welcome. Open an issue first for larger changes.