MCP Browser Extension

MCP Browser Extension

Website and docs: mcp-browser-extension.com · Quickstart · All 43 tools · Install the extension from the Chrome Web Store

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

• Website checks with explicit Chrome permission. Local suspicious-site checks are on by default. After one Chrome permission grant, ordinary sites work automatically and flagged sites need Allow. Named-site approval remains available; --no-site-grants enforces the server's fixed allowlist. Reads and actions are checked in the extension. 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.
• Recent activity in Chrome: the popup shows the latest five activity rows (a tab's open/close pair shares one row); Settings shows up to 100 with outcome filters. This session history contains website names and app keys, without page text, entered values or full URLs.
• Stop access: disconnect all apps from the popup or Settings. The stop survives restarts; Resume connection requires fresh approval for each app. A command already running may finish, and completed actions cannot be undone.
• 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 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:

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

1. Register the MCP server with your host.

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

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

Website access requires app approval and Chrome permission. Suspicious-site checks are on by default; click Allow website access once in the extension. For a fixed named-site policy, use --no-site-grants --allow-domain <glob>. Mutations, downloads, uploads and eval stay off until enabled with --enable-mutations, --enable-downloads, --enable-uploads or --unsafe-enable-eval.

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 still needs approval inside Chrome before using the extension, and stays within the configured domain and capability policy. 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.

Keep transport pairing across restarts. 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). This transport pairing does not grant an app access: every new app session has a separate key and needs Chrome approval.

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

Install MCP Browser Extension from the Chrome Web Store. 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 and click Verify this device. 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.