# mcp-browser-extension [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/Mehmoodqureshi/mcp-browser-extension  
**GitHub Stars:** 6  
**npm Downloads (last month):** 1719  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-browser-extension

## Description
Drive your real Chrome browser over MCP — real logins, real cookies. A stdio MCP server (CLI) plus an MV3 extension, driving Chrome via chrome.scripting/chrome.tabs. Multi-tab batch automation, accessibility snapshots, deny-all security by default.

## Tools
Capabilities this server exposes over MCP:

- **tabs_list** — List open browser tabs.
- **screenshot** — Capture a screenshot (page or element). Default is JPEG (quality 70) at CSS-pixel size, which is several times smaller than PNG and reads fine. Pass format:"png" for lossless, quality 1-100 for JPEG, scale 2 for device pixels on a Retina display or 0.5 to shrink.
- **get_text** — Get visible text of the page or an element.
- **get_html** — Get HTML of the page or an element. Output is capped (see maxBytes) and cut at a tag boundary; narrow it with `selector` rather than raising the cap when you can. Password field values are always blanked.
- **snapshot** — Accessibility snapshot: interactive elements with refs to target by `ref` (more reliable than guessing CSS selectors). Pass diff:true to get only what changed since the last snapshot of this tab - far cheaper in a click/read loop. Password fields appear as secret:true with no value.
- **page_watch** — Save a local page checkpoint and compare it later. Actions: create (name), compare (watchId), list, delete. Stores accessibility labels and state, never form values. Site allowlist still applies.
- **get_cookies** — Cookies for the tab's URL (or url); values need --enable-cookie-values.
- **storage** — Read/write localStorage (or sessionStorage). op: get|set|remove|clear.
- **wait_for** — Wait for a selector or text to appear/disappear.
- **extract_links** — Extract anchors from the page or a subtree. dedupe=true collapses links sharing an href (nav/footer noise); limit caps the count.
- **read_as_markdown** — Read the page (or subtree) as readable markdown.
- **frames_list** — List the tab's frames (the top document plus every iframe the extension can reach), with each frame's id and URL. Use it when a selector that should match does not: the element is probably in one of these frames, and you can then pass frameId (or allFrames:true) to act inside it.
- **print_pdf** — Render the page to PDF through Chrome's own print pipeline and save it to the task's results/ dir. Returns the path and size, not the bytes - a PDF is not something to spend context on.
- **proxy_status** — The active profile's proxy and the IP sites see. The user sets it per Chrome profile; for another IP, profile_use another profile.
- **chrome_status** — Report backend/session status: paired browser profiles and how each was named, and flags for switched-off capabilities.
- **auth_check** — Is the tab sitting on a sign-in wall? Reads the page (URL, title, password fields, sign-in controls) and returns { authRequired, confidence, signals }. Use it after a navigate, or whenever a step fails unexpectedly, to tell "the session expired" apart from "the agent got lost". Pass failOnAuthWall:true to get an [AUTH_REQUIRED] error instead of a verdict, so a harness can bucket the run as an auth failure.
- **profile_use** — Switch the active browser profile (identity). Subsequent downloads, results, screenshots, and the action log are stored under profiles/<name>/. Resets the active task to "default" unless you then call task_new.
- **profile_rename** — Rename an automatically named browser profile (e.g. "profile-2" -> "work"). The name sticks across restarts; its saved artifacts move with it.
- **task_new** — Start a new task (run) under the active profile. Creates profiles/<profile>/tasks/<name>/ with downloads/, results/, screenshots/ and makes it the active task so all captured artifacts land there.
- **tasks_list** — List every task across all profiles under the data dir, with sizes and download counts.
- **task_status** — Report the active profile/task and the folder paths where this run's artifacts are stored.
- **batch** — Run multiple tool calls in one request — parallel (default) or serial. Each op is { tool, args } and goes through the same policy gate, rate limit, and error handling as a direct call. In parallel mode, tab-scoped ops MUST pass an explicit tabId (the active-tab default is unsafe under concurrency). Use to drive several tabs at once (e.g. open tabs, then batch get_text across them). Cannot be nested.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-browser-extension": {
    "command": "npx",
    "args": ["-y","mcp-browser-extension@latest"]
  }
}
```

## Documentation

## What mcp-browser-extension does

mcp-browser-extension lets an MCP-compatible agent operate the Chrome profiles you already use. Instead of starting a separate browser with an empty session, it works through an MV3 Chrome extension installed from the Chrome Web Store or loaded unpacked. Existing Gmail, GitHub, CRM, analytics, administration, and other website sessions can therefore be used without placing passwords or cookies in MCP configuration.

The package is useful for browser automation against sites where an API is unavailable or has not been configured. Agents can read pages, inspect authenticated application screens, perform permitted actions, and work across several tabs. The extension opens agent-controlled pages in background tabs so it does not navigate or remove focus from the tab you are using.

## How it works

The system has two components: the `mcp-browser-extension` npm command and the Chrome extension. The MCP host starts the command, while the extension connects to its localhost WebSocket endpoint. Chrome scripting and tab APIs carry out the browser operations. The extension is required; the package does not launch or attach to its own Chromium instance.

Website access involves approval in Chrome. Suspicious-site checks are enabled by default, and a fixed domain policy can be configured with `--no-site-grants` and one or more `--allow-domain` values. The server can also emit an authentication-required signal when a website session expires, allowing an agent to stop and request that the user signs in again.

## Setup and configuration

Register the server with an MCP host using `npx`, then install the extension from the Chrome Web Store or load it as an unpacked extension. Claude Code can register it with `claude mcp add`; Claude Desktop and other hosts can use an `mcpServers` JSON entry whose command is `npx` and whose package argument is `mcp-browser-extension@latest`.

A minimal command can include an allowed domain:

```bash
npx -y mcp-browser-extension@latest --allow-domain example.com
```

Capabilities that can change or transfer data are opt-in. Use `--enable-mutations` for page mutations, `--enable-downloads` for downloads, `--enable-uploads` for file uploads, and `--unsafe-enable-eval` for evaluation. Uploads can additionally be constrained with `--uploads-dir`. Email verification is enabled by default and can be disabled for trusted local unattended setups with `--no-email-verification` or `MCP_BROWSER_EXTENSION_EMAIL_VERIFICATION=0`.

Transport pairing uses a newly generated token on each start by default. `--persist-token` stores the token with restrictive file permissions for reconnection across restarts, while `MCP_BROWSER_EXTENSION_TOKEN` supplies a token without writing it to disk.

## Tools and capabilities

The tool surface includes 43 tools, including capabilities for:

- Reading page content and accessibility snapshots.
- Operating across multiple tabs with batch requests.
- Checking whether an authenticated session remains valid with `auth_check`.
- Selecting among installed Chrome profiles with `profile_use`.
- Uploading local files through page file inputs when uploads are enabled with `upload_file`.
- Performing mutations, downloads, uploads, and evaluation only when their corresponding controls permit them.

The extension records each call with its URL, decision, duration, and returned byte count. Its popup shows recent activity, and Settings provides additional history and outcome filtering. Access can be disconnected from the popup or Settings; resuming requires fresh approval for each application.

## Limitations and notes

This is an extension-only design, so no browser tool works until the extension is installed and paired. The server does not sign in for the agent and never stores credentials. Password values are not returned, and `--redact` can remove tokens, API keys, and JWTs from page reads.

Mutations, downloads, uploads, and evaluation are disabled unless explicitly enabled. Uploads can expose local files to a destination page, so an uploads directory restriction is recommended for unattended use. A command already in progress may finish after access is stopped, and completed browser actions cannot be undone. The legacy CDP options are accepted for compatibility but ignored.

_Full upstream README: https://allmcps.com/mcp/mcp-browser-extension/readme_