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.

[!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 and Responsible use before pointing it at anything you care about.

---

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

---

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

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.

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.

[!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.

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