chrome-mcp

# MCP Browser Extension

[![CI](https://github.com/Mehmoodqureshi/chrome-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Mehmoodqureshi/chrome-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/%40mehmoodqureshi%2Fchrome-mcp?label=npm)](https://www.npmjs.com/package/@mehmoodqureshi/chrome-mcp)
[![license](https://img.shields.io/npm/l/%40mehmoodqureshi%2Fchrome-mcp?label=license)](LICENSE)

**Website and docs:** [mcp-browser-extension.vercel.app](https://mcp-browser-extension.vercel.app) ·
[Quickstart](https://mcp-browser-extension.vercel.app/docs/quickstart) ·
[All 40 tools](https://mcp-browser-extension.vercel.app/docs/tools) ·
[Install the extension from the Chrome Web Store](https://chromewebstore.google.com/detail/mcp-extension-for-chrome/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 `@mehmoodqureshi/chrome-mcp`, command `chrome-mcp`; the
names predate the rename and stay so existing setups keep working). The extension
comes from the
[Chrome Web Store](https://chromewebstore.google.com/detail/mcp-extension-for-chrome/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-extension-for-chrome/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 the two
steps that must happen inside Chrome:

```text
Set up MCP Browser Extension on this machine by fetching and following
https://raw.githubusercontent.com/Mehmoodqureshi/chrome-mcp/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 chrome-mcp -s user -- \
  npx -y @mehmoodqureshi/chrome-mcp@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": {
    "chrome-mcp": {
      "command": "npx",
      "args": ["-y", "@mehmoodqureshi/chrome-mcp@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`.

> `--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 `~/.chrome-mcp/token` and reused; the extension's
keepalive auto-reconnects with no manual step. `CHROME_MCP_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. Click Connect.** 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 boots
it copies it to `~/chrome-mcp-extension` (`%USERPROFILE%\chrome-mcp-extension` on
Windows; `CHROME_MCP_EXTENSION_DIR` moves it). `chrome://extensions` → enable
**Developer mode** → **Load unpacked** → pick that folder. It pairs itself from a
`pairing.json` the server writes there, and the server refreshes the files on each
boot (never with an older build) so it reloads itself within 30 seconds.

An unpacked copy does not update through Chrome, so its popup suggests the store
copy. Unpacked builds carry the store's public key and so have the same id: load
one *or* the store copy in a Chrome profile, not both. Working from a git clone?
`npm install && npm run build:ext` first; `extension-dist/` is gitignored.

</details>

**Where to see the badge:** it sits on the extension's icon in Chrome's
toolbar, not on the `chrome://extensions` page. Chrome hides new extensions
behind the puzzle-piece button at the right of the address bar, so click that,
find **MCP Browser Extension**, and click the pin next to it once; the icon then
stays in the toolbar. Hover it for the status in words.

| Badge | Meaning |
|---|---|
| green dot | paired and connected |
| yellow dots | connecting |
| grey circle | not paired y