GitHub - smankoo/open-browser-control: Give AI agents control of your Chrome browser. Works with any MCP client.

Give AI agents control of your browser — Chrome or Firefox. Works with Kiro, Claude Code, Claude Desktop, Cursor, and any MCP client.

The AI uses your real browser — your cookies, sessions, and logins. When it hits something it can't handle (sign-in, CAPTCHA, MFA), it asks you to step in, then continues where it left off.

Install either the Chrome or the Firefox extension — the MCP server speaks the same protocol to both.

Quick Start

Step 1: Add MCP config

Add to your MCP client's config:

Kiro — add to .kiro/settings/mcp.json (workspace) or ~/.kiro/settings/mcp.json (global):

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["-y", "open-browser-control"]
    }
  }
}

Claude Code

claude mcp add browser -- npx -y open-browser-control

Claude Desktop / Cursor / other MCP clients

Add to your MCP config file:

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["-y", "open-browser-control"]
    }
  }
}

Step 2: Install the browser extension

Pick whichever browser you'd like the AI to drive.

Chrome — install from the Chrome Web Store:

Open Browser Control on the Chrome Web Store

Firefox

Unpack the extension and load it in Firefox:

npx -y open-browser-control --extension firefox

This prints a path like ~/open-browser-control-extension-firefox. Then:

Open about:debugging#/runtime/this-firefox
Click Load Temporary Add-on…
Pick the manifest.json inside that folder

Firefox clears unsigned temporary add-ons on restart. For a permanent install, use Firefox Developer Edition (xpinstall.signatures.required=false) or sign the extension via AMO.

Chrome — load unpacked

The extension is auto-installed to ~/open-browser-control-extension/ on first run. Load it in Chrome:

Open chrome://extensions/
Enable Developer mode (toggle in top right)
Click Load unpacked
Select the folder: ~/open-browser-control-extension/

Done. The extension auto-connects when your agent starts. No servers to run, no buttons to click.

How It Works

AI Agent          MCP Server              Browser Extension
(Kiro,       ◄──► (npx open-browser-  ◄──► (Chrome: CDP, or
 Claude, ..)      control)                  Firefox: scripting API)
              stdio    ws://localhost:9334    auto-connect

Your agent starts the MCP server automatically (from the config above)
MCP server starts a WebSocket bridge on localhost:9334
The browser extension (Chrome or Firefox) auto-connects (polls every 2s until it finds the bridge)
Agent sends tool calls → extension executes (via Chrome DevTools Protocol on Chrome, or the WebExtensions scripting API on Firefox) → results flow back

Both extensions implement the same JSON protocol over WebSocket, so the MCP server, bridge, and agents never need to know which browser is on the other end.

User/AI Handoff

Mode	What happens
Collaborative (default)	Both user and AI interact with the page
AI Control	AI drives, user watches
User Control	AI paused, user takes over

AI browsing → hits login page → calls browser_request_user("Please sign in")
  → user signs in → clicks "Done" in side panel → AI continues, now authenticated

Browser Tools

19 tools available to the AI:

Tool	What it does
`browser_navigate`	Go to a URL
`browser_get_dom`	Get interactive elements with positions and text (primary way to read pages)
`browser_get_page_info`	URL, title, dimensions, scroll position
`browser_execute_js`	Run JavaScript in page context
`browser_click`	Click by selector, text, or coordinates
`browser_type`	Type text, optionally clear first or press Enter
`browser_scroll`	Scroll up/down/left/right
`browser_keypress`	Press any key with modifiers
`browser_hover`	Hover over an element
`browser_select_option`	Pick from a dropdown
`browser_wait`	Wait for element, text, or fixed time
`browser_screenshot`	Capture page as PNG (use sparingly — DOM tools are faster)
`browser_request_user`	Ask user to take over (sign in, CAPTCHA, etc.)
`browser_new_tab_group`	Create a named tab group for a task
`browser_new_tab`	Open a new tab in the current group
`browser_close_tab`	Close a tab
`browser_switch_tab`	Switch to a tab by ID
`browser_list_tabs`	List all open tabs in this session
`browser_set_session_name`	Set the session name (shown on tab group)

Standalone Use (no MCP)

If you're not using an MCP client:

npx -y open-browser-control --bridge    # starts WebSocket bridge only

Connect your agent to ws://localhost:9334 and send JSON messages:

{"type": "action", "action": "navigate", "id": "1", "params": {"url": "https://example.com"}}
{"type": "action", "action": "click", "id": "2", "params": {"text": "Sign In"}}
{"type": "action", "action": "get_dom", "id": "3"}

CLI

npx -y open-browser-control                 # Start MCP server (default)
npx -y open-browser-control --bridge        # Standalone WebSocket bridge
npx -y open-browser-control --extension     # Print extension install path
npx -y open-browser-control --port 9000     # Custom port
npx -y open-browser-control --help          # Help

Development

git clone https://github.com/smankoo/open-browser-control
cd open-browser-control
npm install
npm run build    # builds both browsers → dist/chrome, dist/firefox
                 # and packages to extension/ and extension-firefox/
npm run dev      # watch mode
npm start        # run MCP server locally

Requirements

Chrome 116+ or Firefox 128+
Node.js 18+