Browser Controller

What browser-controller does

The browser-controller MCP server gives an MCP-compatible agent control of a browser that is already open. Its Chrome extension executes commands in the user’s real pages, so agents can work with existing sessions, cookies, and logins rather than creating a new browser profile or asking the user to authenticate again.

Actions identify a tabId instead of relying on whichever tab is active. This lets multiple agents work on different tabs through one shared daemon while keeping each tab’s element references, logs, and network buffers separate. A tab opened by one session is owned by that session until it closes; calls from another session fail with TAB_LOCKED.

The project belongs in the 📂 Browser Automation category. It is suited to browser-based verification, authenticated workflows, and debugging pages that an agent has modified or needs to inspect.

How it works

The installation has three local components: an MCP client, a Node.js daemon, and a Manifest V3 browser extension. The MCP entry point communicates over stdio and starts the background daemon when needed. The daemon listens on port 7225, maintains sessions, and multiplexes agent requests through one authenticated WebSocket connection to the extension.

Each connected browser profile has its own connection. The extension routes a request to the tab named by the caller and serializes concurrent actions on that tab. Actions on different tabs can run in parallel. While a tool is operating, a translucent shield blocks manual input on that tab; an optional agent cursor can show mouse movement.

Browser input uses the Chrome DevTools Protocol, including clicks, typing, keyboard events, wheel input, and drags. These are trusted browser events. If the debugger cannot attach, the operation returns DEBUGGER_UNAVAILABLE instead of falling back to synthetic events. Communication is bound to localhost and uses a token and enrollment secret for pairing.

Setup and configuration

The browser-controller MCP server is installed from the repository rather than from npm or the Chrome Web Store. Node.js 20 or newer and Chrome, Chromium, or Edge are required.

1. Clone the repository and run npm install.
2. Run npm run build to compile the TypeScript into mcp-server/dist/.
3. Open chrome://extensions, enable Developer mode, and load the repository’s extension/ directory as an unpacked extension.
4. Register mcp-server/dist/index.js in the MCP client with the node command and the absolute path to that file.

Cursor, Claude Desktop, and Windsurf each provide MCP configuration locations in their settings or configuration files. An optional --agent <name> argument changes the name shown for the connection in the extension popup.

Tools and capabilities

The browser-controller MCP server provides 17 tools in version 3.0, using a shared target locator. A target can be an element reference such as e12, visible text, viewport coordinates, or a CSS selector. Shadow roots and same-origin iframes are searched; cross-origin iframes are reported as unreadable.

Supported operations include tab selection and navigation, page interaction, DOM inspection, console-style JavaScript with top-level await, console and network log retrieval, request mocking, browser emulation, and CDP access. browser_batch combines up to 50 calls in one round trip and stops when a step fails. Results are compact text, while failures return an error code and message.

Limitations and notes

The browser must be connected through the extension, and the debugger must be available for real input actions. The browser shows Chrome’s “being debugged” banner while attached. The daemon and extension require a compatible protocol handshake; peers from before version 3.0 are rejected with an error.

The control plane is supported only on localhost at 127.0.0.1; the project does not provide a remote or n8n listener. Request mocks apply to one tab. A stalled tab can be replaced during navigation, in which case the result includes a note with the replacement tabId. The extension is loaded manually and the project is not distributed through the Chrome Web Store or npm.