BrowserMCP/mcp

What it is

Browser MCP is a bridge that lets AI coding assistants (Claude Code, Cursor, VS Code, Codex, Claude Desktop, etc.) control your own Chrome browser — with your existing logins, cookies, and profile — in separate tabs. Everything runs locally on your machine; nothing is sent to a cloud service.

It has two parts:

• A Chrome extension (available on the Chrome Web Store, or buildable from source) that acts as a remote control for the browser.
• An MCP server (a small Node.js program) that your AI app launches and talks to. MCP (Model Context Protocol) is the standard way AI apps call external tools — here, the tool is "browser."

How it works

1. Your AI app starts the MCP server with npx @browsermcp/mcp@latest. This server spawns a daemon (a background process) for your user account.
2. The AI app sends browser tool calls to the server, which forwards them to the daemon.
3. The daemon drives Chrome's tabs using Playwright (a browser automation library), but it doesn't talk to Chrome directly — it goes through the extension.
4. The extension is a thin relay that uses Chrome's chrome.debugger API to actually control the browser. It only accepts connections from the daemon on 127.0.0.1 (your own machine).

Security model

The extension is deliberately restrictive:

• Pairing: The first time you use it on a computer, the extension's popup shows a six-digit code. You must click Allow only after verifying that code matches the one your AI app displays. This prevents any random local process from hijacking your browser.
• Hard rules: Even if the daemon asks, the extension refuses to open incognito windows, browser-internal pages (like chrome://), or extension pages. It also stops all control when you press Stop in the popup.
• Local-only: The extension only talks to the daemon on 127.0.0.1 — no internet traffic.

Components (repo layout)

Folder	Package	Purpose
packages/mcp	@browsermcp/mcp	The MCP server and the daemon
packages/protocol	@browsermcp/protocol	The communication protocol between extension and daemon, including pairing
packages/extension-core	@browsermcp/extension-core	The extension's browser-control logic: connection, pairing, debugger relay, tab rules, badge
apps/extension	@browsermcp/extension	The actual Chrome extension built from this repo, including its popup UI

Building from source

Requirements: Node.js 24+, pnpm (enable via corepack enable), and Chrome or a Chromium-based browser (Edge, Brave, Arc…). Firefox is not supported because it lacks the debugger API.

git clone https://github.com/BrowserMCP/mcp.git browsermcp
cd browsermcp
pnpm install
pnpm build

Then load the unpacked extension from apps/extension/.output/chrome-mv3 via chrome://extensions (Developer mode → Load unpacked). The self-built extension has the same ID as the Web Store version, so you can't run both at once — disable the store version if you have it.

To use your built server instead of the npm one, point your AI app's MCP config at the local file:

{
  "mcpServers": {
    "browsermcp": {
      "command": "node",
      "args": ["/path/to/browsermcp/packages/mcp/dist/index.js"]
    }
  }
}

Note: npx @browsermcp/mcp@latest also works with the self-built extension — it's the same server, just published from this repo.

Updating

git pull
pnpm install
pnpm build

Then reload the extension in chrome://extensions and restart your AI apps if they run the server from this folder. The extension and server will warn you if one side is too old for the other.

Development

• pnpm lint, pnpm format / pnpm format:fix — code style (Oxlint, Oxfmt)
• pnpm typecheck, pnpm test — TypeScript checks and unit tests (Vitest). Server tests need Playwright's Chromium: pnpm --filter @browsermcp/mcp exec playwright-core install chromium
• pnpm smoke — builds everything in dev mode, loads the extension in headless Chromium, and drives it through the server like an AI app would, using random ports and a temporary BROWSER_MCP_HOME so it never touches your real Browser MCP setup. Screenshots land in apps/extension/.output/smoke/
• pnpm --filter @browsermcp/extension build:dev — a development build at apps/extension/.output/chrome-mv3-dev

License & trademarks

Apache-2.0. The name "Browser MCP" and its logo are trademarks — if you publish a modified version, you must rename it and change the icon (see TRADEMARKS.md).