convez.ai
MCP ServerAutomaçãoIntermediário
ofershap

Real Browser MCP

ofershap/real-browser-mcp

Agente IA vê e controla seu navegador Chrome real com sessões ativas

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que integra um agente de IA com seu navegador Chrome real, permitindo que o agente veja, navegue e interaja com páginas web mantendo sessões e logins existentes. Combina um servidor MCP com uma extensão Chrome para dar ao seu assistente IA visão e controle genuínos do navegador.

Instalação

$npx convez-ai ofershap/real-browser-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
59
Forks
13
Acompanhando
1
Saúde
85%
Último commit
há 3 dias
Versão
v1.4.0
Issues abertas
0
Contribuidores
2

Casos de uso

  • Verificação de código em páginas web ao vivo com o agente
  • Automação de tarefas web mantendo login e contexto
  • Debugging de aplicações web com agente navegando como usuário real
  • Testes end-to-end com IA interagindo com interface do navegador

Veredito

Ferramenta diferenciada que fecha um gap crítico: permite que agentes IA vejam e manipulem o navegador real em vez de fazer web scraping cego. Especialmente útil para verificação de deployments e testes de aplicações web, com integração direta no Cursor.

README

A tradução para o português deste README ainda está na fila.


You ship a fix. Your agent says "done, please verify." You alt-tab to Chrome, navigate to the page, log in, click around, find the bug.

Your agent just wrote the code. It could also verify it. It already has your browser open right there. It just can't see it.

Now it can.


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

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.


How Others Compare

Real Browser MCPPlaywright MCPChrome DevTools MCP
Uses your existing browserYesNo, launches newPartial, needs debug port
Sessions and cookiesAlready thereFresh profileManual setup
Works behind corporate SSOYesNoDepends
SetupExtension + MCP configHeadless browserChrome 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

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

ToolWhat it does
browser_snapshotAccessibility tree with element refs. Compact mode (default) returns only interactive elements
browser_screenshotCapture what's on screen
browser_textExtract raw text from page or element
browser_findQuery elements by CSS selector

Interact

ToolWhat it does
browser_clickClick by ref or CSS selector
browser_click_textClick by visible text. Works through React portals and overlays
browser_typeType into inputs and contenteditable fields
browser_press_keyKey combos (Enter, Escape, Ctrl+A)
browser_scrollScroll pages and virtual containers
browser_hoverTrigger tooltips and dropdowns
browser_selectPick from native <select> dropdowns
browser_waitWait for elements to appear or disappear

Navigate

ToolWhat it does
browser_navigateGo to a URL in the active tab
browser_tabsList, create, close, or focus tabs

Debug

ToolWhat it does
browser_consoleConsole output (log, warn, error)
browser_networkXHR/fetch requests with status codes
browser_evaluateRun JavaScript via Chrome DevTools Protocol
browser_handle_dialogHandle alert/confirm/prompt dialogs

Configuration

Env varDefaultWhat it does
WS_PORT7225WebSocket 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 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
CommandWhat it does
npm run buildCompile TypeScript
npm run devWatch mode
npm testRun tests
npm run typecheckType check without emitting
npm run setup:cursorInstall Cursor rule + command

FAQ

That's the whole point. The extension runs inside your actual Chrome - same cookies, same sessions, same local storage. No re-authentication needed.

No. The MCP server and extension talk over WebSocket on localhost. Nothing leaves your machine. There's no analytics, no telemetry, 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.

They launch a new browser instance from scratch - no state, no cookies, no sessions. You have to replay the full login flow every time. This connects to the browser you already have open with everything already loaded.


Contributing

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

Author

Made by ofershap

LinkedIn GitHub


README built with README Builder

License

MIT © Ofer Shapira

Ver o original no GitHub

Bom para

Relacionados