# stealth-browser-mcp

An [MCP](https://modelcontextprotocol.io) server that gives an AI assistant a
real Chrome browser which stays logged in.

Most browser-automation tools hand the model a fresh, empty browser. This one
drives a **persistent Chrome profile**, so once you have logged into a site
yourself — through whatever 2FA, CAPTCHA or device-approval it demands — the
model can keep using that session on later runs without ever seeing your
password.

For sites that will not tolerate a scripted login, it adds two escape hatches:
credentials pulled from the **macOS Keychain** at fill time, and **WebAuthn
passkeys** replayed through Chrome's virtual authenticator.

> [!WARNING]
> This is a power tool. It gives a language model control of a browser holding
> your live sessions, and it is capable of typing your stored passwords into
> pages the model chooses. Read [SECURITY.md](SECURITY.md) and
> [Responsible use](#responsible-use) before pointing it at anything you care
> about.

---

## Contents

- [How it works](#how-it-works)
- [Requirements](#requirements)
- [Install](#install)
- [Connect it to an MCP client](#connect-it-to-an-mcp-client)
- [The first login](#the-first-login)
- [Tool reference](#tool-reference)
- [Storing credentials in the Keychain](#storing-credentials-in-the-keychain)
- [Passkeys](#passkeys)
- [Configuration](#configuration)
- [Verifying stealth](#verifying-stealth)
- [Troubleshooting](#troubleshooting)
- [Responsible use](#responsible-use)
- [License](#license)

---

## How it works

```
        MCP client (Claude Code, Claude Desktop, Cursor, …)
                          │
                          │  JSON-RPC over stdio
                          ▼
              ┌───────────────────────────┐
              │   stealth-browser-mcp     │
              │   16 tools, one browser   │
              └─────┬───────────────┬─────┘
                    │               │
     credentials    │               │   CDP + Puppeteer
                    ▼               ▼
        ┌───────────────────┐   ┌───────────────────────┐
        │  macOS Keychain   │   │  Google Chrome        │
        │  stealth-mcp:*    │   │  + stealth plugin     │
        │  passwords,       │   │  + WebAuthn virtual   │
        │  passkey material │   │    authenticator      │
        └───────────────────┘   └───────────┬───────────┘
                                            │
                                            ▼
                              ┌─────────────────────────┐
                              │  Persistent profile dir │
                              │  cookies · localStorage │
                              │  IndexedDB · sessions   │
                              └─────────────────────────┘
```

Three pieces do the work:

**Persistence.** Chrome is launched against a fixed `userDataDir` instead of a
throwaway one. Log in once interactively and the cookies survive across every
later run — the usual reason automation breaks on real sites disappears.

**Stealth.** [`puppeteer-extra-plugin-stealth`](https://github.com/berstend/puppeteer-extra)
patches the well-known automation tells, and the server layers on a few more:
`navigator.webdriver` is undefined, `window.chrome.runtime` is present,
`HeadlessChrome` is stripped from the user agent, and
`--disable-blink-features=AutomationControlled` is set. Clicks move the mouse
along a path to a jittered point inside the target; typing is character by
character with 30–100 ms gaps.

**Session reuse rather than session creation.** The design goal is to avoid
automating logins at all. Keychain autofill and passkey replay exist for the
cases where you cannot.

## Requirements

- **Node.js 18 or newer**
- **Google Chrome.** Puppeteer's bundled Chromium works, but a real Chrome
  build is noticeably less detectable.
- **macOS**, if you want the Keychain and passkey features. Everything else —
  navigation, extraction, screenshots, the persistent profile — is
  cross-platform. The Keychain layer shells out to `/usr/bin/security` and will
  fail on other platforms; the browser tools do not touch it.

## Install

```bash
git clone https://github.com/lauyuen/stealth-browser-mcp.git
cd stealth-browser-mcp
npm install
```

Optionally copy the example environment file and edit it:

```bash
cp .env.example .env
```

Confirm the browser launches and the evasions are active:

```bash
npm run check-stealth
```

## Connect it to an MCP client

The server speaks stdio. Point your client at `src/server.js` with an absolute
path.

**Claude Code**

```bash
claude mcp add stealth-browser -- node /absolute/path/to/stealth-browser-mcp/src/server.js
```

**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "stealth-browser": {
      "command": "node",
      "args": ["/absolute/path/to/stealth-browser-mcp/src/server.js"]
    }
  }
}
```

**Any other MCP client** — same shape, plus an optional profile override:

```json
{
  "mcpServers": {
    "stealth-browser": {
      "command": "node",
      "args": ["/absolute/path/to/stealth-browser-mcp/src/server.js"],
      "env": {
        "BROWSER_PROFILE_DIR": "/absolute/path/to/a/private/profile/dir"
      }
    }
  }
}
```

Restart the client afterwards. `browser_status` is the quickest way to confirm
the connection is live.

## The first login

Before the model can use a site, seed the profile yourself:

```bash
npm run login -- https://example.com
```

A visible Chrome window opens using the same profile the MCP server will use.
Log in normally — password managers, 2FA prompts, CAPTCHAs, "remember this
device", all of it. Press <kbd>Enter</kbd> in the terminal when you are done and
the session is flushed to disk.

Every later MCP run inherits that session. Repeat per site. Sessions expire on
the site's own schedule, so re-run this when a site logs you out.

## Tool reference

### Navigation and interaction

| Tool | Arguments | Notes |
| --- | --- | --- |
| `browser_navigate` | `url`, `waitUntil?` | `waitUntil` is one of `load`, `domcontentloaded`, `networkidle0`, `networkidle2` (default). Returns final URL, title and HTTP status. |
| `browser_click` | `selector` | Scrolls the element into view, then moves the mouse to a jittered point inside it before pressing. |
| `browser_type` | `selector`, `text`, `clearFirst?` | Types one character at a time with randomised delays. |
| `browser_scroll` | `direction?`, `distance?` | `up` or `down`, pixels (default 600). |
| `browser_wait_for` | `selector?`, `milliseconds?` | Waits for an element, sleeps, or both. |

### Reading the page

| Tool | Arguments | Notes |
| --- | --- | --- |
| `browser_extract_text` | `selector?` | Strips scripts and styles; returns text plus structured links and form fields. The cheapest way to let a model read a page. |
| `browser_extract_html` | `selector?` | Raw `outerHTML`. Use when you need exact markup or attributes. |
| `browser_screenshot` | `fullPage?` | Returns a PNG as MCP image content. |
| `browser_evaluate` | `script` | Runs JavaScript in page context and returns the result. See the warning in [SECURITY.md](SECURITY.md). |

### Session and authentication

| Tool | Arguments | Notes |
| --- | --- | --- |
| `browser_autofill_login` | `service`, `account`, `usernameSelector?`, `passwordSelector`, `submitSelector?` | Reads the password from the Keychain and types it. The secret is never returned to the model. |
| `keychain_store_credential` | `service`, `account`, `password` | Writes to the Keychain under `stealth-mcp:<service>`. Prefer the CLI — see below. |
| `passkey_enable_virtual_authenticator` | `rpId?`, `account?` | With both arguments, injects a stored passkey. With neither, attaches an empty authenticator ready for registration. |
| `passkey_save_registration` | `rpId`, `account` | Captures a freshly registered credential and stores it. |

### Browser lifecycle

| Tool | Arguments | Notes |
| --- | --- | --- |
| `browser_status` | — | Connection state, tab count, current URL, profile path, whether an authenticator is attached. |
| `browser_open_interactive_window` | `url?` | Reopens the current session in a visible window so you can solve a CAPTCHA or approve a 2FA prompt by hand, then hand control back. |
| `browser_close` | — | Closes gracefully and flushes cookies to disk. |

The browser launches headless by default and is reused across calls.
`browser_open_interactive_window` is the one tool that switches it to a visible
window.

## Storing credentials in the Keychain

Passwords live in the macOS Keychain under the `stealth-mcp:` service prefix —
never in a file in this repository, and never in the model's context.

```bash
npm run keychain set github you@example.com     # prompts; input is not echoed
npm run keychain get github you@example.com     # confirms presence, prints length only
npm run keychain delete github you@example.com
```

The model then triggers a login without ever learning the secret:

```jsonc
// browser_autofill_login
{
  "service": "github",
  "account": "you@example.com",
  "usernameSelector": "#login_field",
  "passwordSelector": "#password",
  "submitSelector": "input[type='submit']"
}
```

`service` is an arbitrary label you choose — it only has to match between the
CLI and the tool call.

You can also pass the password as a trailing CLI argument for scripting, but it
will land in your shell history and the process list, so the command warns you
when you do.

## Passkeys

Chrome exposes a [WebAuthn virtual authenticator](https://chromedevtools.github.io/devtools-protocol/tot/WebAuthn/)
over the DevTools Protocol — a software authenticator intended for testing
WebAuthn flows. This server drives it, and persists the resulting key material
in the Keychain so it survives across runs.

**Registering an automation passkey**

1. `passkey_enable_virtual_authenticator` with no arguments.
2. Navigate to the site's "add a passkey" flow and complete it. The virtual
   authenticator answers the challenge; no OS prompt appears.
3. `passkey_save_registration` with the site's `rpId` and your account.

**Using it later**

`passkey_enable_virtual_authenticator` with `rpId` and `account` injects the
stored credential before you navigate, and the site signs you in without a
prompt.

> [!CAUTION]
> A passkey held this way is a file, not a hardware key. It can be copied,
> which is exactly the property real passkeys exist to prevent. Register
> automation-only passkeys with it. Do not use it for the passkey guarding your
> email, your bank, or anything else whose loss would matter.

## Configuration

All settings are environment variables, read from the process environment or a
`.env` file. See [.env.example](.env.example).

| Variable | Default | Purpose |
| --- | --- | --- |
| `BROWSER_PROFILE_DIR` | `~/.config/stealth-browser-mcp/profile` | Persistent Chrome profile. Holds live sessions — keep it private and out of version control. |
| `CHROME_EXECUTABLE_PATH` | Platform default | Chrome binary to drive. Falls back to Puppeteer's Chromium if the path does not exist. |
| `NAV_TIMEOUT` | `45000` | Navigation and selector timeout, in milliseconds. |

Chrome launch flags and the default 1280×800 viewport live in
[`src/config.js`](src/config.js). Several flags trade security for
compatibility — [SECURITY.md](SECURITY.md#known-weakenings) explains which and
why you may want to remove them.

## Verifying stealth

```bash
npm run check-stealth
```

Reports `navigator.webdriver`, `window.chrome`, `window.chrome.runtime`, the
plugin count, `navigator.languages` and the effective user agent, then prints
the resolved profile and Chrome paths.

For a harder check, point the browser at a fingerprinting page — for example
`bot.sannysoft.com` or `abrahamjuliot.github.io/creepjs` — with
`browser_navigate` followed by `browser_screenshot`.

No stealth setup is undetectable. Well-defended sites combine fingerprinting
with behavioural analysis, IP reputation and account history, and will still
spot automation. Treat this as "does not trip the obvious checks", not as
invisibility.

## Troubleshooting

**"Failed to launch the browser process" / profile is locked.** Chrome allows
one process per profile directory. Close any Chrome you started manually
against the same directory. The server clears stale `Singleton*` lock files on
launch and will reconnect to a live instance over its DevTools port, but a
running Chrome that owns the profile wins.

**A site logs the model out or blocks it.** The stored session has expired.
Re-run `npm run login -- <url>`.

**Selectors do not match.** Call `browser_extract_html` on a narrow selector
and let the model read the real markup instead of guessing. Single-page apps
often mount inputs late — `browser_wait_for` first.

**A CAPTCHA appears.** Call `browser_open_interactive_window`, solve it
yourself, and continue. The solved state persists in the profile.

**Keychain errors on Linux or Windows.** Expected — that layer is macOS-only.
The browser tools work everywhere; the credential and passkey tools do not.

## Responsible use

This project exists to let an assistant act on sites *you already have an
account on*, using sessions *you established yourself*. That is the intended
scope, and the persistent-profile design reflects it.

Anti-detection and credential automation can obviously be pointed elsewhere.
Before you run it against a site, consider:

- **The site's terms of service.** Many prohibit automated access outright.
  Evading a bot defence may breach a contract you agreed to, and in some
  jurisdictions unauthorised access carries criminal liability. Being able to
  bypass a control is not permission to.
- **Consent.** Automate accounts that belong to you, or that you have written
  authorisation to act on. Someone else's credentials in your Keychain is not
  consent.
- **Load.** Rate-limit yourself. Respect `robots.txt` where it applies.
  Automation that costs a site real money is a good way to get the technique
  banned for everyone.
- **Other people's data.** Pages the model reads flow into your MCP client's
  provider. Do not pipe third parties' personal information through it.

Contributions that exist primarily to defeat a specific site's protections,
harvest credentials, or scale abuse will not be merged.

## License

[MIT](LICENSE) © Yuen Lau