io.github.ofershap/real-browser

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

<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor" height="32" />

Or add manually in Cursor Settings > MCP > "Add new MCP server":

{
  "mcpServers": {
    "real-browser": {
      "command": "npx",
      "args": ["-y", "real-browser-mcp"]
    }
  }
}

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

<img src="https://developer.chrome.com/static/docs/webstore/branding/image/iNEddTyWiMfLSwFD6qGq.png" alt="Available in the Chrome Web Store" height="58" />

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.

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

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.

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

git clone https://github.com/ofershap/real-browser-mcp.git
cd real-browser-mcp
npm install
npm run build
npm test

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.

Author

_{README built with README Builder}

License

MIT © Ofer Shapira