Skip to main content
Glama
stealth-browser-mcp

stealth-browser-mcp

by lauyuen

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


Contents


Related MCP server: byob

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

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

Available Tools

16 tools
browser_autofill_loginA

Automatically fill and submit a login form using credentials stored securely in macOS Keychain.

Inputs: account (required), service (required), passwordSelector (required), submitSelector, +1 more.

browser_clickA

Click an element on the page using human-like mouse movement and click delays.

Inputs: selector (required).

browser_closeA

Gracefully close the browser and flush session cookies/storage to disk.

Inputs: no named parameters.

browser_evaluateB

Execute a custom JavaScript expression in the active page context and return the result.

Inputs: script (required).

browser_extract_htmlC

Extract outer HTML of a specific element or the entire page DOM.

Inputs: selector.

browser_extract_textA

Extract cleaned text, links, and forms from the page for LLM reading.

Inputs: selector.

browser_navigateA

Navigate the stealth browser to a target URL with persistent authentication.

Inputs: url (required), waitUntil.

browser_open_interactive_windowA

Opens a non-headless visible Chrome window on the user desktop so the user can manually solve a CAPTCHA or complete 2FA.

Inputs: url.

browser_screenshotA

Capture a screenshot of the current page for visual inspection.

Inputs: fullPage.

browser_scrollB

Scroll the viewport up or down.

Inputs: distance, direction.

browser_statusB

Check the current status of the browser instance, active tabs, and persistent profile path.

Inputs: no named parameters.

browser_typeB

Type text into an input or textarea with realistic human keystroke timing delays.

Inputs: text (required), selector (required), clearFirst.

browser_wait_forB

Wait for a CSS selector to appear or sleep for a specified duration in milliseconds.

Inputs: selector, milliseconds.

keychain_store_credentialA

Store a username and password securely in macOS Keychain so the browser agent can log in automatically later.

Inputs: account (required), service (required), password (required).

passkey_enable_virtual_authenticatorC

Enables a Chrome DevTools Protocol (CDP) WebAuthn virtual authenticator and optionally injects a stored Passkey credential from Keychain.

Inputs: rpId, account.

passkey_save_registrationB

Captures newly registered Passkey credentials from the virtual authenticator and saves them to macOS Keychain for future automated logins.

Inputs: rpId (required), account (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 16 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: navigation, login, passkey management, keychain storage, clicking, typing, screenshotting, text extraction, HTML extraction, JS evaluation, scrolling, waiting, interactive window, status, and close. The overlap between extract_text and extract_html is minor and well-explained by their descriptions.

    Naming Consistency5/5

    Tool names follow a consistent pattern with functional prefixes (browser_, passkey_, keychain_) and descriptive verb_noun or verb_object combinations. All verbs are clear and consistently styled (snake_case), making the set predictable and scannable.

    Tool Count5/5

    16 tools is appropriate for a browser automation server covering navigation, interaction, authentication, extraction, and lifecycle management. Each tool earns its place and the count is neither sparse nor bloated for the intended scope.

    Completeness4/5

    The tool surface covers core browser automation workflows: navigation, login, passkey handling, interaction, content extraction, and browser lifecycle. Minor gaps exist such as explicit back/forward navigation or download handling, but these do not critically hinder typical automation tasks.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI agents to authenticate with websites using a real Chromium browser with anti-detection measures and human-in-the-loop support for captchas and 2FA. Features stealth browsing, human-like interactions, and persistent session storage to automate and resume login workflows.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Lets AI assistants control your real Chrome browser to perform web tasks like reading pages, taking screenshots, clicking, and typing, using your existing logged-in sessions.
      145
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants and terminal users to control a logged-in Chrome browser, performing actions like opening pages, searching, filling forms, and taking screenshots without re-authentication.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to access authenticated websites by reusing your existing browser profile and cookies, so you never share passwords and sessions persist between runs.
      5
      5
      MIT