mcp-browser-extension

# MCP Browser Extension

[![CI](https://github.com/Mehmoodqureshi/mcp-browser-extension/actions/workflows/ci.yml/badge.svg)](https://github.com/Mehmoodqureshi/mcp-browser-extension/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/mcp-browser-extension?label=npm)](https://www.npmjs.com/package/mcp-browser-extension)
[![license](https://img.shields.io/npm/l/mcp-browser-extension?label=license)](LICENSE)

**Website and docs:** [mcp-browser-extension.com](https://mcp-browser-extension.com) ·
[Quickstart](https://mcp-browser-extension.com/docs/quickstart) ·
[All 42 tools](https://mcp-browser-extension.com/docs/tools) ·
[Install the extension from the Chrome Web Store](https://chromewebstore.google.com/detail/mcp-browser-extension/jelfhdlkhbfmlpbghoeaepijllcnplgh)

**Let Claude use the Chrome you are already logged into.** Not a fresh
automated browser that greets every site as a stranger — *your* Chrome, with
your sessions, your cookies, your 2FA already done. If you can see a page in
your browser, your agent can read it, without logging in again and without
pasting credentials anywhere.

Most browser MCP servers launch their own Chromium and hand your agent a
signed-out window. MCP Browser Extension does the opposite: an MV3 extension dials into a
localhost WebSocket server and drives the browser you already have open, through
`chrome.scripting`/`chrome.tabs`. Works with Claude Code, Claude Desktop, and any
other MCP host.

MCP Browser Extension has two parts: the extension, and a small MCP server you run
with `npx` (npm package and command: `mcp-browser-extension`). The extension
comes from the
[Chrome Web Store](https://chromewebstore.google.com/detail/mcp-browser-extension/jelfhdlkhbfmlpbghoeaepijllcnplgh)
or loaded unpacked.

> **This build is extension-only.** It never launches or attaches a Chromium of
> its own, so **the extension is required, not optional** — without it, no tool
> can run. The CDP flags (`--cdp-fallback`, `--no-cdp-fallback`, `--cdp-endpoint`,
> `--prefer`) are still accepted for back-compat but are **ignored**.

> **Full design:** [`docs/BLUEPRINT.md`](docs/BLUEPRINT.md) — architecture, wire
> protocol, the complete tool surface, the extension manifest, the security
> model, and the phased build plan.

## Use Claude in your signed-in Chrome

You are already signed in to Gmail, GitHub, your analytics dashboards, the admin
panel, the CRM. MCP Browser Extension lets Claude (Claude Code, Claude Desktop, or any
other MCP host) work in those same tabs: no re-login, no second 2FA prompt, no
password or cookie in a config file. The extension runs inside your normal
Chrome, so a page the agent opens is the page you would see.

- **Gmail** — read a thread or search results in a tab you already have open.
- **GitHub** — go through PRs, issues and settings pages as yourself, private
  repositories included.
- **Dashboards** — pull numbers from analytics, billing or admin screens that
  have no API, or whose API you never set up.

Other tools drive a signed-in Chrome too (the `hangwin/mcp-chrome` extension,
for one), so the question is what you get on top of the session:

- **A per-domain allowlist, deny-all by default.** With no flags the agent can
  read nothing. `--allow-domain mail.google.com --allow-domain github.com`
  opens exactly those hosts (`*.example.com` covers a domain and its
  subdomains); every other site is refused before the call reaches the page.
  Reads are gated, not only clicks, and the extension re-checks the same policy
  on its side. Mutations, eval, downloads and uploads are separate opt-ins.
- **Password values are never returned**, and `--redact` scrubs tokens, API
  keys and JWTs out of page reads.
- **An audit trail**: every call is logged with the URL, the allow/deny
  verdict, duration and bytes returned.
- **It stays out of your tab**: the agent opens its own tabs in the background
  and works there, so the page you are on is never navigated, clicked or pulled
  out of focus. `batch` reads many of them at once in one call.
- **Several Chrome profiles**: load the extension in your work and personal
  profiles and switch between them with `profile_use`.
- **`auth_check`**: when a session does expire, the agent gets an
  `[AUTH_REQUIRED]` signal instead of a confusing timeout, so it can stop and
  ask you to sign in again. MCP Browser Extension never holds credentials or signs in for
  you.

Setup is two pieces: the MCP server (`npx`, below) and the extension, which you
can **[install from the Chrome Web Store](https://chromewebstore.google.com/detail/mcp-browser-extension/jelfhdlkhbfmlpbghoeaepijllcnplgh)**
or load from the folder the server unpacks.

## Quickstart

### Up and running in one paste

Hand this to your AI agent (Claude Code, Cursor, Windsurf, anything MCP) and it
installs the server, wires it into the client, and walks you through installing
the extension, verifying your email, and pairing Chrome:

```text
Set up MCP Browser Extension on this machine by fetching and following
https://raw.githubusercontent.com/Mehmoodqureshi/mcp-browser-extension/main/SETUP.md
exactly, step by step. Work autonomously and verify each step.
```

Prefer to read before you run an agent on your machine? [`SETUP.md`](SETUP.md)
is the exact file the agent follows. The manual steps are below.

**1. Register the MCP server** with your host.

<details open>
<summary><b>Claude Code (terminal)</b> — one command, no config file to find</summary>

```bash
claude mcp add mcp-browser-extension -s user -- \
  npx -y mcp-browser-extension@latest \
  --allow-domain example.com --enable-mutations --persist-token
```

Everything **before** `--` belongs to Claude Code; everything **after** it is this
server's command and flags. Keep the `--` or `--allow-domain` gets read as a
Claude Code option.

`-s user` registers it for every project on your machine. Use `-s local` (the
default) for just the current project, or `-s project` to write a `.mcp.json`
your team can commit.

Check it came up with `claude mcp list`. After upgrading the server, reconnect it
with `/mcp` inside a session — no restart needed.

</details>

<details>
<summary><b>Claude Desktop</b> and other MCP hosts — JSON config</summary>

```jsonc
{
  "mcpServers": {
    "mcp-browser-extension": {
      "command": "npx",
      "args": ["-y", "mcp-browser-extension@latest",
               "--allow-domain", "example.com", "--enable-mutations",
               "--persist-token"]
    }
  }
}
```

</details>

By default everything is **deny-all** (no domains, no eval, no mutations). Grant
exactly what you need with `--allow-domain <glob>` (repeatable), `--enable-mutations`,
`--enable-downloads`, `--enable-uploads`, `--unsafe-enable-eval`, or `--unsafe-all-domains`.

Email verification is on by default. For a trusted, local unattended setup, you
can opt out with `--no-email-verification` (or set
`MCP_BROWSER_EXTENSION_EMAIL_VERIFICATION=0`). This skips the email prompt and
the Firebase access service, so no email or device grant is sent there. The
local MCP client can then use the browser within the configured domain and
capability policy without an account check. Treat every process that can launch
or reach this local server as trusted. This option is rejected with `--tunnel`
and does not turn off telemetry or the npm update check.

> `--enable-uploads` permits `upload_file` (setting local file(s) on a page's file
> `<input>`). It is **off by default** because sending local files to a page is an
> exfiltration risk; it is also gated by the destination-domain allowlist. Pair it
> with `--uploads-dir <path>` to restrict uploads to files inside that directory
> (`..` traversal is blocked) — strongly recommended for unattended use.

**Pair once, never again.** Both examples above include `--persist-token`, which
is what makes the pairing survive a restart — drop it if you'd rather have the
stricter default described next.

Without `--persist-token` a fresh token is minted every boot (the secure
default), which means re-pairing the extension on each restart. With it, the
token is stored 0600 at `~/.mcp-browser-extension/token` and reused; the extension's
keepalive auto-reconnects with no manual step. `MCP_BROWSER_EXTENSION_TOKEN` pins the token
explicitly (and is never written to disk).

**2. Install the extension** — **required**; the server can drive nothing without it.

**[Install MCP Browser Extension from the Chrome Web Store](https://chromewebstore.google.com/detail/mcp-browser-extension/jelfhdlkhbfmlpbghoeaepijllcnplgh)**.
One click, no Developer mode, and **Chrome keeps it updated for you**. This is
the way to install it.

**3. Verify your email.** In your MCP client, ask the agent to call
`chrome_status`. On this first browser tool call, the client shows an email
prompt. Enter an address you can access, then open the sign-in link sent to
that address. The waiting tool reports **Email verified** and continues.

If the tool returns `ACCESS_PENDING`, ask the agent to call `chrome_status`
again to keep waiting on the same link. You do not need another email or a
verification code. The MCP client must support interactive input prompts
(MCP elicitation). If no prompt appears, enable interactive prompts in your
client and retry; installing the extension alone does not activate access.

**4. Click Connect if Chrome is not already paired.** A fresh install opens the
extension's Settings with a
**Connect** button (it is in the toolbar popup too). Click it, allow the one
permission Chrome asks for, and you are paired: the server registers a small
helper with Chrome every time it starts, and the button asks it for the port and
token. Chrome lets only this extension talk to that helper. If the server ever
changes its token, the extension fetches the new one by itself. Nothing to copy
or paste.

<details>
<summary>Developers: load it unpacked instead</summary>

The extension also ships inside the npm package, and every time the server b