# browser-controller [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/compnew2006/browser-controller  
**GitHub Stars:** 7  
**npm Downloads (last month):** 29  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/browser-controller

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

## Tools
Capabilities this server exposes over MCP:

- **browser_navigate** — - `url` (required): an address (scheme optional: `https://` is added; `http://` for `localhost`, `127.0.0.1` and `[::1]`), or `back`, `forward`, `reload`.
- **browser_tabs** — - `action`: `list` (default), `close` or `focus`. `close` and `focus` need `tabId`.
- **browser_snapshot** — - `tabId` (required).
- **browser_text** — - `tabId` (required); `target` (the element); `maxChars` (20000; 100–100000).
- **browser_screenshot** — - `tabId` (required); `target` (crop to the element's box); `region` (`{x, y, width, height}` in CSS px, crop to a rectangle).
- **browser_inspect_element** — - `tabId`, `target` (required).
- **browser_click** — - `tabId`, `target` (required; a point `x,y` is allowed).
- **browser_type** — - `tabId` (required); `target`; `text`; `key`; `clear` (false); `submit` (false). Give at least one of `text`, `key`, `clear` or `submit`.
- **browser_fill** — - `tabId` (required); `fields` (1–50 entries of `{target, value}`; `value` is a string, a number, a boolean or an array of strings).
- **browser_scroll** — - `tabId` (required); `target`; `dy` and `dx` (pixels).
- **browser_wait** — - `tabId` (required); exactly one of `target`, `url` or `ms`; `gone` (false; with `target`); `timeout` (10000; 1–50000).
- **browser_evaluate** — - `tabId`, `expression` (required); `timeout` (5000; 1000–30000).
- **browser_handle_dialog** — - `tabId`, `accept` (required, boolean); `promptText` (answer for a prompt).
- **browser_logs** — - `tabId` (required); `kind`: `console` or `network` (omitted = both); `filter` (a substring of the message text, or of the URL for network); `errors` (false: console errors, and failed or 4xx/5xx requests); `limit` (50; 1–200); `clear` (false); `since` (a request id: only the requests after it); `…
- **browser_mock** — - `tabId` (required); `rules` (up to 50 entries; omitted = list; `[]` = clear).
- **browser_emulate** — - `tabId` (required). All other fields are optional and apply to this tab only:
- **browser_batch** — - `actions` (required; 1–50 entries of `{tool, params}`; any tool except `browser_batch`); `tabId` (optional default).

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "browser-controller": {
    "command": "npx",
    "args": ["-y","browser-controller"]
  }
}
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/browser-controller/readme_