chrome-mcp

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. chrome-mcp 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.

Distributed as an npx CLI (the MCP server) plus an extension, from the Chrome Web Store 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 — 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. chrome-mcp 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.
• Background tabs and batch: open pages with active: false and read many at once in one call, without stealing focus from the tab you are working in.
• 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. chrome-mcp 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 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:

Set up chrome-mcp 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 is the exact file the agent follows. The manual steps are below.

1. Register the MCP server with your host.

claude mcp add chrome-mcp -s user -- \
  npx -y @mehmoodqureshi/chrome-mcp \
  --allow-domain example.com --enable-mutations --persist-token

{
  "mcpServers": {
    "chrome-mcp": {
      "command": "npx",
      "args": ["-y", "@mehmoodqureshi/chrome-mcp",
               "--allow-domain", "example.com", "--enable-mutations",
               "--persist-token"]
    }
  }
}

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. Load the extension — required; the server can drive nothing without it.

Two ways to get it:

• Install from the Chrome Web Store — one click, no Developer mode, and Chrome keeps it updated. The Web Store build is reviewed before each release, so it can trail the npm package by a version; it pairs with any server and simply skips features it predates.
• Load the bundled folder (below) — always matches the npm package you just installed, and the right choice when you want the newest behaviour.

The extension ships prebuilt inside the npm package, and every time the server boots it copies it to a plain folder right under your home directory:

~/chrome-mcp-extension          (macOS / Linux)
%USERPROFILE%\chrome-mcp-extension   (Windows)

So after step 1 has started the server once (restart your client, or /mcp in Claude Code), the folder is already there. To create it without a client, or to print the exact path:

npx -y @mehmoodqureshi/chrome-mcp --extension-path

Then chrome://extensions → enable Developer mode → Load unpacked → pick chrome-mcp-extension in your home folder. After upgrading the package the server refreshes the files on its next boot and the extension reloads itself within 30 seconds; nothing to click. CHROME_MCP_EXTENSION_DIR moves the folder somewhere else. (Working from a git clone instead? Run npm install && npm run build:ext first — extension-dist/ is gitignored, and the server mirrors it to the same home folder.)

3. Pair it — usually nothing to do. Every time the server boots it writes pairing.json (mode 0600, never shipped in the tarball) into the very chrome-mcp-extension folder you just loaded. The extension reads that file from its own folder on startup and pairs itself, so the toolbar badge turns green with no token to paste. Load the extension before the server has ever run? It re-checks every 30 seconds and pairs as soon as the file appears.

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 Extension for Chrome, and click the pin next to it once; the icon then stays in the toolbar. Hover it for the status in words.