MCP Browser ExtensionIntroduction
What chrome-mcp is, why it drives your real Chrome instead of a fresh Chromium, and where to start.
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.comopens exactly those hosts (*.example.comcovers 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
--redactscrubs 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 withactive: falseand 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.
Where to go next
- Quickstart: register the server and load the extension in three steps.
- Agent setup: hand one URL to your agent and let it do the install.
- Tools reference: all the tools, with arguments.
- Security: the deny-all default and what you can opt into.
- Architecture: the blueprint, wire protocol and build plan.