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](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:

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 Code (terminal) — one command, no config file to find

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.

Claude Desktop and other MCP hosts — JSON config

{

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

). 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 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](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 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.

If your client suppresses the prompt (for example, in YOLO/bypass mode), does not support MCP elicitation, or the dialog is dismissed, the server automatically opens a temporary local verification form in your browser. The tool also returns ACCESS_INPUT_REQUIRED with the link, so you can open it yourself if necessary on the computer running the MCP server. Enter your email in the browser form, and open the sign-in link from your inbox. Click Verify this device, then call chrome_status to continue. The local form expires after 10 minutes; call the tool again for a fresh one. Opening the form does not send an email, and access remains blocked until the email link and device grant are verified. 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.

5. Approve the app connection in Chrome. Run chrome_status, then open the extension popup's App connections section. Compare the key fingerprint with the one in the tool result and click Approve for 8 hours. App names are supplied by the app; the key identifies this particular session. Retry the tool after approving. A question-mark badge and the popup show pending requests, even if the client hides its prompts. Approve, deny, revoke and restore connections directly in the popup or in Settings.

Each app session has its own signing key, held only in that server session's memory. Approval applies to this Chrome profile for eight hours. Restarting the app's MCP connection creates a new key and needs a new approval. Remove access blocks further commands from tha