stealth-browser-mcp

An MCP 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.

Contents

• How it works

• Requirements

• Install

• Connect it to an MCP client

• The first login

• Tool reference

• Storing credentials in the Keychain

• Passkeys

• Configuration

• Verifying stealth

• Troubleshooting

• Responsible use

• License

Related MCP server: agent-browser-mcp

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

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:

cp .env.example .env

Confirm the browser launches and the evasions are active:

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

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

{
  "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:

{
  "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:

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 Enter 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

Reading the page

Session and authentication

Browser lifecycle

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.

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:

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

Configuration

All settings are environment variables, read from the process environment or a .env file. See .env.example.

Chrome launch flags and the default 1280×800 viewport live in src/config.js. Several flags trade security for compatibility — SECURITY.md explains which and why you may want to remove them.

Verifying stealth

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 © Yuen Lau