real-browser-mcp

The missing piece in AI coding: your agent can now see your REAL browser.

Your Agent Works in a Void

Your agent writes code, runs tests, passes CI. Then says "please verify in the browser." So you alt-tab to Chrome, navigate to the right page, log in, find the button, click it, check if it broke something. That's the loop. Every time.

Think about it - the agent that just refactored your entire checkout flow can't click a single button on the page to see if it still works.

Playwright MCP? It launches a blank browser. No cookies, no sessions, nothing. If your app is behind auth or corporate SSO, you're spending half the time just getting the agent logged in. And for a quick "did my CSS change break the sidebar?" check, that's absurd.

This is the missing piece. An MCP server + Chrome extension that plugs the agent directly into the browser already on your screen. Your sessions. Your cookies. Your local storage. Nothing to set up, nothing to re-authenticate.

_{Animation by remotion-readme-kit}

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"]
    }
  }
}

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.

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

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

{
  "mcpServers": {
    "browser-work": {
      "command": "npx", "args": ["-y", "real-browser-mcp"]
    },
    "browser-personal": {
      "command": "npx", "args": ["-y", "real-browser-mcp"],
      "env": { "WS_PORT": "9333" }
    }
  }
}

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

FAQ

Contributing

Bug reports, feature requests, and PRs welcome. Open an issue first for larger changes.

Author

License

MIT © Ofer Shapira