# browser-controller

> MCP server + Chrome extension that gives AI agents control of your real browser with existing sessions and logins.

## What it does

browser-controller is a Model Context Protocol (MCP) server paired with a Chrome extension. It lets AI coding agents (Cursor, Claude, Windsurf, and any MCP client) interact with the user's actual browser - not a headless copy, not a new instance. The browser the user already has open, with their tabs, cookies, sessions, and logins intact.

## Key differentiator

Unlike Playwright MCP or Chrome DevTools MCP, which launch or attach to a separate browser, browser-controller controls the browser the user is already using. For projects with authentication, complex state, or corporate SSO, this means no re-login, no session setup, no cookie recreation.

## Tools (22 + 1 meta tool)

Navigation: browser_navigate, browser_tabs

Interaction: browser_click, browser_click_text, browser_type, browser_press_key, browser_scroll, browser_hover, browser_select, browser_drag, browser_fill_form, browser_upload_file, browser_wait

Reading: browser_snapshot (compact mode default - interactive elements only), browser_screenshot, browser_text, browser_find

JavaScript: browser_evaluate (execute arbitrary JS in page context, supports async/await), browser_run_action (CDP-based, bypasses CSP)

Dialogs: browser_handle_dialog (handle alert/confirm/prompt)

Debugging: browser_console, browser_network

Discovery: browser_tools (meta tool - list/search/activate tools; with BROWSER_CONTROLLER_PROGRESSIVE=1 only this tool is visible upfront: initial tool-definition tokens drop ~96%, ~75-80% net for a typical task activating 3-5 tools)

## Architecture

- MCP server: Node.js/TypeScript, communicates with AI agent via stdio

- Chrome extension: Manifest V3, communicates with MCP server via WebSocket on localhost

- All communication is local. No cloud, no telemetry, no data exfiltration.

## Install

npm: npx browser-controller

Chrome extension: Load unpacked from the extension/ directory

## Links

- Repository: https://github.com/compnew2006/browser-controller

- npm: https://www.npmjs.com/package/browser-controller

- License: MIT