stealth-browser-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@stealth-browser-mcp go to my GitHub and show my latest pull requests"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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/securityand 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 installOptionally copy the example environment file and edit it:
cp .env.example .envConfirm the browser launches and the evasions are active:
npm run check-stealthConnect 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.jsClaude 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.comA 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 |
|
|
|
|
| Scrolls the element into view, then moves the mouse to a jittered point inside it before pressing. |
|
| Types one character at a time with randomised delays. |
|
|
|
|
| Waits for an element, sleeps, or both. |
Reading the page
Tool | Arguments | Notes |
|
| Strips scripts and styles; returns text plus structured links and form fields. The cheapest way to let a model read a page. |
|
| Raw |
|
| Returns a PNG as MCP image content. |
|
| Runs JavaScript in page context and returns the result. See the warning in SECURITY.md. |
Session and authentication
Tool | Arguments | Notes |
|
| Reads the password from the Keychain and types it. The secret is never returned to the model. |
|
| Writes to the Keychain under |
|
| With both arguments, injects a stored passkey. With neither, attaches an empty authenticator ready for registration. |
|
| Captures a freshly registered credential and stores it. |
Browser lifecycle
Tool | Arguments | Notes |
| — | Connection state, tab count, current URL, profile path, whether an authenticator is attached. |
|
| 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. |
| — | 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.comThe 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
passkey_enable_virtual_authenticatorwith no arguments.Navigate to the site's "add a passkey" flow and complete it. The virtual authenticator answers the challenge; no OS prompt appears.
passkey_save_registrationwith the site'srpIdand 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.
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 |
|
| Persistent Chrome profile. Holds live sessions — keep it private and out of version control. |
| Platform default | Chrome binary to drive. Falls back to Puppeteer's Chromium if the path does not exist. |
|
| 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-stealthReports 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.txtwhere 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 toolsbrowser_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_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
Scored across 16 tools
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.
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.
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.
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
Let AI agents use your real, signed-in Chrome: tabs, clicks, forms, screenshots and video.
Let your AI agent operate any website through a real, logged-in browser session.
Let AI agents use any website you're logged in to. Sessions stay encrypted on your machine.
Logs your AI agent into websites, catches verification codes, and asks you before anything risky.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceEnables 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.-
- AlicenseNot gradedqualityCmaintenanceLets 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.145MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseAqualityCmaintenanceEnables AI agents to access authenticated websites by reusing your existing browser profile and cookies, so you never share passwords and sessions persist between runs.55MIT