agent-browser-use-extension

An MCP server + Chrome extension that lets any MCP-compatible AI agent (Claude Desktop, Claude Code, Cursor, etc.) drive your existing Chrome window — with your real cookies, your real logins, and your real profile.

No separate Chromium. No Playwright restart loop. No login-on-every-run. The agent talks to the extension over a local HTTP queue, and the extension runs commands inside whichever tab it's pointed at.

Why

Most "AI controls a browser" stacks (Playwright, browser-use, Stagehand, etc.) launch a fresh Chromium with a clean profile. That's great for stateless scraping and terrible the moment you need to be logged in somewhere. This project takes the opposite approach: the agent attaches to the Chrome you're already using.

What's in this repo

• extension/ — Chrome MV3 extension. Polls a local bridge, runs commands in your tabs, posts results back. Renamable via the options page; works on any URL.
• mcp-server/ — Node MCP server. Boots the bridge, registers one MCP tool per browser action, and forwards calls.

MCP tools exposed

Tool	What it does
list_tabs	Every open tab across windows.
get_active_tab	The currently focused tab.
open_tab	Open a new tab at a URL.
close_tab	Close a tab by id.
navigate	Send an existing tab to a new URL.
get_dom	Return text/HTML/outerHTML of a selector.
extract_anchors	Bulk-grab anchors as {href, text, aria}.
click	Click the first match of a selector.
type_text	Set an input's value + fire events; optional form submit.
scroll	Scroll a tab N times by D pixels.
evaluate	Run JS in the page main world; return JSON.
screenshot	Visible-area PNG/JPEG of a tab, returned as a data: URL.
ext_version	Health check — extension version + UA.

Install

See docs/INSTALL.md for the full walkthrough. Short version:

1. Load the extension. chrome://extensions → Developer mode → "Load unpacked" → pick the extension/ folder. The toolbar shows a popup with bridge: down (expected — server not running yet).
2. Run the MCP server. From the repo root:

   cd mcp-server && npm install && npm start

   Or from anywhere once published: npx agent-browser-use-mcp.
3. Wire your MCP client. Example for Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

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

4. Open the extension popup. It should now show bridge: up.

Renaming

The extension is meant to be rebranded for your own workflow. Click the extension icon → Open settings. Three fields:

• Display name — what shows in the popup and toolbar tooltip.
• Bridge endpoint — change if you've moved the MCP server off 127.0.0.1:8765.
• Poll interval — how aggressively the worker checks for queued commands while alive. The 30s Chrome-alarm fallback fires regardless.

The manifest name still says "Agent Browser Use" (Chrome shows that in chrome://extensions), but everything user-facing during normal use reads from your settings.

Security model

This extension gives any MCP client connected through the local server full read/write access to your live browser session, including authenticated sites. It's intended for local agent work on your own machine.

• The bridge only listens on 127.0.0.1 (no LAN exposure).
• The MCP server runs over stdio — only processes that the OS lets spawn it can talk to it.
• There is no authentication between the extension and the bridge — by design, since both run on your loopback interface. Don't expose port 8765 outside your machine.

Architecture

┌────────────────┐  stdio JSON-RPC   ┌──────────────────┐  HTTP /poll  ┌─────────────────┐
│  MCP client    │ ◄───────────────► │  MCP server      │ ◄──────────► │  Chrome ext.    │
│ (Claude, etc.) │                   │  + local bridge  │  /result     │  service worker │
└────────────────┘                   └──────────────────┘              └─────────────────┘
                                                                              │
                                                                       chrome.scripting
                                                                              ▼
                                                                       ┌──────────────┐
                                                                       │  Your tabs   │
                                                                       └──────────────┘

License

MIT — see LICENSE.