Real Browser

real-browser-mcp

Agentic browsers give agents a new browser. Coding agents need yours.

MCP + Chrome extension for the Chrome you already have open:

cookies, SSO, staging sessions, the bug you already reproduced.

---

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.

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":

{

"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

1. Open chrome://extensions and enable Developer mode (toggle in the top right)
2. 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 Plugins 1.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.

Spec and tooling: agent-plugins.org.

---

Why this exists (the agentic browser gap)

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

---

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

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

Interact

Navigate

Debug

---

Configuration

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

| npm run setup:cursor | Install C