This MCP server connects AI agents to your already-open Chrome browser, giving them access to your real sessions, cookies, and SSO — no new browser needed.
👁️ See the page
browser_snapshot – accessibility tree with element refs, compact mode shows only interactive elements
browser_screenshot – capture visible area as PNG/JPEG
browser_text – extract raw text from page or scoped element
browser_find – find elements via natural language (e.g. "login button")
🖱️ Interact
browser_click – click by ref or CSS selector, with left/right/middle/double‑click
browser_click_text – click by visible text (works through portals/overlays)
browser_type – type into inputs/contenteditable, optional clear‑before‑typing
browser_press_key – press keyboard keys/combos (Enter, Escape, Ctrl+A, etc.)
browser_scroll – scroll by pixels, direction, position, or to a specific element
browser_hover – trigger tooltips/dropdowns
browser_select – pick <select> options by value/label/index
browser_wait – wait for elements to appear, disappear, or a fixed delay
🧭 Navigate
browser_navigate – go to URL with navigation‑completion control
browser_tabs – list, create, close, focus tabs
🐛 Debug
browser_console – read logs/warnings/errors, optionally clear after reading
browser_network – read XHR/fetch requests with statuses, filter by URL pattern
browser_evaluate – execute arbitrary JavaScript in page context
browser_handle_dialog – accept/dismiss alert/confirm/prompt dialogs
Enables the identification and querying of web elements using CSS selectors for automated interaction and data extraction.
Integrates with Google Chrome via a dedicated extension to allow AI agents to view, navigate, and interact with the user's active browser session in real-time.
Provides a tool to evaluate and execute custom JavaScript code directly within the browser context via the Chrome DevTools Protocol.
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).
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
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: 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.
Or load from source:
git clone https://github.com/ofershap/real-browser-mcp.gitOpen 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.
Related MCP server: byob
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.
Stack | What the agent gets | Where it fails for coding agents |
Playwright MCP / Puppeteer | New browser, clean state | No SSO cookies, no "the tab I already opened" |
Cloud agentic browsers | Remote browser / VM | Separate login, not your IDE-local Chrome |
Chrome DevTools MCP (CDP / autoConnect) | DevTools-oriented attach | Chrome 136+ refuses |
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.
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 |
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 cursorThis 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 claudeAdds an AGENTS.md to your project root. Claude Code auto-discovers it.
See agent-config/ for manual installation or to customize the rules.
18 tools. Grouped by purpose.
See
Tool | What it does |
| Accessibility tree with element refs. Compact mode (default) returns only interactive elements |
| Capture what's on screen |
| Extract raw text from page or element |
| Query elements by CSS selector |
Interact
Tool | What it does |
| Click by ref or CSS selector |
| Click by visible text. Works through React portals and overlays |
| Type into inputs and contenteditable fields |
| Key combos (Enter, Escape, Ctrl+A) |
| Scroll pages and virtual containers |
| Trigger tooltips and dropdowns |
| Pick from native |
| Wait for elements to appear or disappear |
Navigate
Tool | What it does |
| Go to a URL in the active tab |
| List, create, close, or focus tabs |
Debug
Tool | What it does |
| Console output (log, warn, error) |
| XHR/fetch requests with status codes |
| Run JavaScript via Chrome DevTools Protocol |
| Handle alert/confirm/prompt dialogs |
Env var | Default | What it does |
|
| 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).
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 testsStack: 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 testCommand | What it does |
| Compile TypeScript |
| Watch mode |
| Run tests |
| Type check without emitting |
| Install Cursor rule + command |
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.
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.
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.
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.
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.
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.
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.
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.
Bug reports, feature requests, and PRs welcome. Open an issue first for larger changes.
README built with README Builder
MIT © Ofer Shapira
Click an element on the page using a ref from snapshot or a CSS selector
Inputs: ref, button, selector, doubleClick.
Click an element by its visible text content. Works on React dropdowns, portals, and overlays that may not appear in snapshots. CSP-safe (no eval). Prefers deepest matching element.
Inputs: text (required), exact, index.
Read console messages (log, warn, error) from the browser
Inputs: clear.
Drag from one element or position to another. Uses CDP mouse events for reliable drag-and-drop. Provide either refs/selectors or explicit x,y coordinates.
Inputs: endX, endY, steps, endRef, +5 more.
Execute JavaScript in the page and return the result. Use for DOM queries, reading page state, or any operation not covered by other tools.
Inputs: expression (required).
Fill multiple form fields in a single call. Supports text inputs, selects, checkboxes, and contentEditable elements. Reduces round-trips compared to calling browser_type for each field individually. Optionally submit the form after filling.
Inputs: fields (required), submit.
Find elements on the page using natural language (e.g. "login button", "search input"). Returns refs you can use with click/type.
Inputs: query (required), limit.
Handle JavaScript dialogs (alert, confirm, prompt). Dialogs block page interaction until handled.
Inputs: action (required), promptText.
Hover over an element to trigger tooltips, dropdown menus, or hover states
Inputs: ref, selector.
Read network requests made by the page. Filter by URL pattern.
Inputs: clear, filter.
Press a keyboard key or combination (Enter, Escape, Tab, ArrowDown, etc). Supports modifiers like Ctrl+A, Cmd+C.
Inputs: key (required), ref, selector, modifiers.
Run a self-contained JavaScript action object in the page context via CDP. The code must be an expression that evaluates to an object with an execute(params) method. Returns the action result directly. Bypasses CSP restrictions.
Inputs: code (required), actionParams.
Capture a screenshot of the visible page area
Inputs: format, quality.
Scroll the page or an element. Supports pixel offsets, scrolling to elements, and named positions (top/bottom). Works with virtual scroll containers used by social media sites.
Inputs: amount, position, selector, direction, +1 more.
Select an option from a dropdown/select element
Inputs: ref, index, label, value, +1 more.
Get an accessibility tree snapshot of the page. Returns element refs you can use with click, type, and other tools. Use compact mode (default) for smaller output - only interactive elements.
Inputs: compact, selector.
Manage browser tabs and the extension-managed tab group. list/create/close/focus tabs. name puts the tab into a Real Browser MCP tab group and sets the group title (emoji in the title is shown as the group icon). ungroup removes the tab from its group.
Inputs: action (required), url, color, tabId, +1 more.
Extract raw text content from the page or a specific element
Inputs: selector, maxLength.
Type text into an input element
Inputs: text (required), ref, clear, selector.
Upload a file through a file input element. Uses CDP DOM.setFileInputFiles — works even on strict-CSP pages. Provide the local file path and either a ref from snapshot, a CSS selector targeting the file input, or omit both to auto-find the first input[type="file"].
Inputs: ref, files, filePath, selector.
Wait for a condition: element to appear, element to disappear, or a fixed delay. Useful for SPAs and dynamic content.
Inputs: delay, state, timeout, selector.
Execute a WebMCP tool on the current page by name with a JSON input object. Use browser_webmcp_list_tools first to discover names and schemas. Returns null when the tool triggers a navigation.
Inputs: name (required), input.
List WebMCP tools the current page registers for agents (document.modelContext.getTools()). Returns supported:false when the browser or page has no WebMCP support.
Inputs: no named parameters.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 24 tools
Most tools map to a clearly distinct browser action, and descriptions do real work separating near-neighbors (browser_type vs browser_fill_form, browser_click vs browser_click_text vs browser_find). The main soft spots are browser_evaluate, browser_run_action, and browser_webmcp_execute_tool, which all execute code-ish things in the page and could be confused without careful reading.
Everything uses a uniform browser_ prefix followed by snake_case action words, so the set reads as one coherent namespace. The longer browser_webmcp_* names still follow the same pattern rather than breaking convention.
24 tools is on the heavy side, but browser automation genuinely needs this breadth (input, snapshots, dialogs, tabs, network, console, WebMCP). Each tool covers a real capability rather than duplicating another, though a few (click_text, find, run_action) could plausibly be folded into their general-purpose siblings.
The surface covers the full interaction lifecycle: navigate, observe (snapshot/text/screenshot/find), interact (click/type/select/hover/drag/upload), wait, and diagnose (console/network), plus tab management. Minor gaps remain around history navigation, cookies/storage, iframe or window targeting, and downloads.
Hosted Web Crawler MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Browz hosted MCP (free public beta): let an AI app drive your own Browz browser profiles from anywhere. Connect https://mcp.gobrowz.com/mcp and sign in with your Browz account (OAuth) or an agent token. Each call is relayed to the Browz app on your computer, which must be online with Remote control on and have a hardware security chip (Mac Secure Enclave or TPM 2.0). 17 tools: profiles, tabs, navigate, snapshot, act, wait, screenshot. Cookies, downloads and stored sign-ins stay on your computer.
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
