MCP Stealth Chrome

An MCP server with 173 tools that gives an AI agent a real Chrome browser and an HTTP client with Chrome's TLS fingerprint.

It drives Chrome over CDP with nodriver, so there is no WebDriver and the identity stays that of your real browser and machine. Requests that need no browser go through curl_cffi, which is much lighter than rendering a page. Search and page reading work without an API key.

Use the browser when a page needs JavaScript, a login or a person looking at it. Use HTTP when you only need the data.

• ✅ Real Chrome over CDP, with no WebDriver
• ✅ HTTP with the TLS fingerprint of Chrome, Firefox or Safari
• ✅ Search and page reading without an API key
• ✅ Real mouse input, and results that say what actually happened
• ✅ Passwords and cookies hidden from tool output by default
• ✅ Several browsers side by side, each with its own profile
• ✅ Works with Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Droid and other MCP clients

Install

You need uv and Chrome or Chromium. uv takes care of Python 3.11+.

Then add the server to your client. Open the one you use:

claude mcp add stealth-chrome --scope user -- uvx mcp-stealth-chrome@latest

claude mcp add stealth-chrome -- uvx mcp-stealth-chrome@latest

{
  "mcpServers": {
    "stealth-chrome": {
      "command": "uvx",
      "args": ["mcp-stealth-chrome@latest"]
    }
  }
}

{
  "mcpServers": {
    "stealth-chrome": {
      "command": "uvx",
      "args": ["mcp-stealth-chrome@latest"]
    }
  }
}

{
  "servers": {
    "stealth-chrome": {
      "command": "uvx",
      "args": ["mcp-stealth-chrome@latest"]
    }
  }
}

{
  "mcpServers": {
    "stealth-chrome": {
      "command": "uvx",
      "args": ["mcp-stealth-chrome@latest"]
    }
  }
}

{
  "context_servers": {
    "stealth-chrome": {
      "command": {
        "path": "uvx",
        "args": ["mcp-stealth-chrome@latest"]
      }
    }
  }
}

[mcp_servers.stealth-chrome]
command = "uvx"
args = ["mcp-stealth-chrome@latest"]

{
  "mcpServers": {
    "stealth-chrome": {
      "command": "uvx",
      "args": ["mcp-stealth-chrome@latest"]
    }
  }
}

{
  "mcp": {
    "stealth-chrome": {
      "type": "local",
      "command": ["uvx", "mcp-stealth-chrome@latest"],
      "enabled": true
    }
  }
}

{
  "mcpServers": {
    "stealth-chrome": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-stealth-chrome@latest"]
    }
  }
}

{
  "mcpServers": {
    "stealth-chrome": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-stealth-chrome@latest"]
    }
  }
}

See docs/INSTALL.md for verification and troubleshooting.

solve_turnstile_oscursor needs the optional os-cursor extra. On macOS, use uvx 'mcp-stealth-chrome[os-cursor]' in your client config ("args": ["mcp-stealth-chrome[os-cursor]@latest"]), or install it with uv tool install 'mcp-stealth-chrome[os-cursor]'. Then give the app or terminal that runs your client Accessibility and Screen Recording permission in System Settings > Privacy & Security. server_status shows under os_cursor whether this is ready. Windows and Linux backends exist but have not been field-tested.

Usage examples

An agent usually reads the page, then acts on the refs it got back:

browser_launch(url="https://example.com")
browser_snapshot()
click(ref="e3")
fill(ref="e5", value="hello")

Log in once by hand, then reuse the session headless. This is the most reliable way past a login wall, because the site sees a session it already trusts:

browser_launch(url="https://target.com/login")
# log in by hand in the window
storage_state_save(filename="target.json")
browser_close()

browser_launch(url="https://target.com/dashboard", headless=true,
               storage_state_path="~/.mcp-stealth/storage-states/target.json")

Log in with the browser, then fetch data over HTTP with the same cookies:

http_request(url="https://target.com/v1/data", impersonate="chrome", use_browser_cookies=true)

Run several accounts side by side, each with its own profile:

spawn_browser("account_2", url="https://target.com", headless=true)
switch_instance("account_2")
click(ref="e7")
switch_instance("main")

Find out what protects a page before choosing an approach:

browser_launch(url="https://unknown-site.com")
detect_anti_bot()
# {"detected": ["Cloudflare"], "recommended_tools": [...]}

See what a button would send on a real account, without sending it:

dry_run()
click(ref="e12")
intercept_log()
dry_run(enable=false)

Test results

Sites change, so read these as results from the screenshots below and not as a guarantee.

Speed and size, measured

Measured in November 2026 on one Mac (M4 Pro, Chrome 157, headless, a throwaway profile), with both servers driven over MCP by the same script. The other server is Google's chrome-devtools-mcp 1.12.0. Each number is the median of 5 runs, or of 9 clicks. One machine and one day, so read the ratios, not the digits.

• ✅ Faster at opening pages, clicking, filling and reading, and smaller snapshots. A snapshot here lists what can be acted on; the other server's lists the whole accessibility tree including text, so the two are not the same content.
• ❌ Slower to start, heavier in memory, and its tool list costs a client that loads every definition about five times as much. profile_mode="light" brought one page to about 630 MB in 7 processes, at the cost described under Speed, memory and disk.
• Tokens were counted with the o200k_base tokenizer as an estimate.

Cloudflare Turnstile

click_turnstile, verify_cf and auto_verify click through CDP. When a challenge is still there afterwards, their result says so and names solve_turnstile_oscursor.

One call moves the checkbox from "Verify you are human" to "Success!". This demo uses Cloudflare's test sitekey and returns a dummy token, so it shows that the click lands on the widget. It does not show that a protected site lets you through.

• ✅ Finds and clicks the embedded widget (.cf-turnstile, [data-sitekey], or a challenges.cloudflare.com iframe). Earlier runs also passed the dash.cloudflare.com login and nopecha.com/captcha/turnstile, not retested since
• ❌ click_turnstile does not get through Cloudflare's full-page "Just a moment..." challenge. On nopecha.com/demo/cloudflare, the click earned a cf_clearance cookie, but the page stayed at status 403, in 3 of 3 tries, one of them with the VPN off
• ✅ solve_turnstile_oscursor got the main browser through the same page in 3 of 3 tries: status 200, title "NopeCHA - CAPTCHA Demo", no challenge, checked from the main browser. Measured in November 2026 on one macOS machine with one home IP. It is not a claim about other sites, other IPs, or Windows and Linux

bot.sannysoft.com

navigator.webdriver is missing, WebDriver Advanced passes, Chrome and its plugins read as normal, and WebGL reports the real GPU.

areyouheadless

Antoine Vastel's public test reports "You are not Chrome headless" for a Chrome controlled by this server.

browserscan.net

Every signal it checks reads "Normal", including WebDriver, Selenium, CDP and headless Chrome.

TLS fingerprint

Measured at tls.browserleaks.com. Each impersonation shows the JA3 of the browser it names, and a plain Python client does not. Hashes change with browser versions.

httpx:                JA3 37f7d09ced1a845dc48872abc1a29d7b   python-httpx/0.28.1
impersonate=chrome:   JA3 f830262a93191fd695c65531282d5657   Chrome/146.0.0.0
impersonate=firefox:  JA3 6f7889b9fb1a62a9577e685c1fcfa919   Firefox/147.0
impersonate=safari:   JA3 ecdf4f49dd59effc439639da29186671   Safari/605.1.15

reCAPTCHA v2 images

Five runs in a row on Google's demo page, with a fresh profile and a vision model through an OpenAI-compatible API:

Run 1: passed, 2169-char token, tiles [3,4,7],        146 s
Run 2: passed, 2126-char token, tiles [0,2,4,7],       80 s
Run 3: passed, 2169-char token, tiles [1,2,4,8],      143 s
Run 4: passed, 2148-char token, tiles [1,4,5,6,8,9],  126 s
Run 5: passed, 2169-char token, tiles [0,3,4],         69 s
Average: 113 s

Limits

• DataDome, Kasada, PerimeterX/HUMAN and ChatGPT's managed Turnstile are hard to pass with open source tools. A session saved after a manual login is the most reliable option, and commercial services may be needed in production.
• Datacenter IPs and fresh profiles get blocked more often. For search engines, a warm profile with engine="brave" returns the most, and an empty result page usually comes from the environment.
• Headless is easier to detect, so keep headless=false on difficult sites.
• A Chrome profile can only be open once at a time. A second browser on the same profile moves to a separate one and says so.
• Closed shadow roots cannot be read.
• On Windows, tests saw Google Chrome read back none of a profile's cookies after a relaunch, so a login may not survive a restart there. Linux and macOS keep them. This is being looked into.

Profiles and privacy

privacy=True starts from an empty profile, deletes it on close, and picks one proxy when you pass a pool (a|b). It does not change the identity. User agent, Chrome version, operating system, language and timezone stay those of the real browser and machine in every mode, since a made-up identity on a real engine contradicts itself. To use a logged-in account, leave privacy off.

You can override identity for one launch: fingerprint={"user_agent": ..., "accept_language": ..., "platform": ..., "timezone": ...}. Fields you leave out stay real. Client hints and a missing navigator.platform are derived from the user agent so they agree with it, and navigator.languages comes from accept_language without the ;q= weights.

To use logins from your own browser, list_chrome_profiles shows every Chromium-family browser on the machine and clone_chrome_profile copies one into an isolated profile. The source is only ever opened read-only.

A browser started with browser_launch over stdio stays open until you close it. Instances from spawn_browser and browsers in HTTP mode close after BROWSER_IDLE_TIMEOUT.

Runtime data lives in ~/.mcp-stealth/: profile/, profiles/<id>/, screenshots/, exports/, storage-states/, window-state/. An app/ folder left by 0.13.0 is removed.

Reopening the last tabs

browser_launch(restore_tabs=True) reopens the tabs this instance had on this profile when the server last closed it: browser_close, close_instance, close_all_instances, the idle timeout, a Quit, or the server exiting because its client went away, which is what happens when an agent session is put to sleep. spawn_browser(restore_tabs=True) does the same for a named instance. Chrome's own session restore stays off, because restored window placement opened windows that could not be seen.

• ✅ Pages open behind the app you are using, the way tab_new opens them, in the order tab_list showed, and the tab that was selected is selected again. Measured on macOS: 0 ms frontmost for the restored browser.
• Without a url, the first saved page loads in the first tab. With a url, that page stays first and selected, the saved pages follow, and a saved page with exactly that URL is not opened twice.
• ✅ The result lists each page as reopened (final URL, status) or failed (why), with secret URL parameters masked. It says plainly when there is no saved list, when the list cannot be read, and when it is older than 30 days (MCP_STEALTH_RESTORE_TABS_MAX_DAYS), and it never fails the launch.
• The list is saved when the server closes the browser, about 2 seconds after tool calls, and every 30 seconds while the browser runs, so a server that was killed still leaves the last list it saw. Saving takes about 1 ms. A Quit closes every window before anything can read them, so the list saved before the Quit stays: a browser with no pages never replaces a saved list. Only http, https and file pages are kept, up to 30.
• persistent=False and privacy=True keep no tabs.
• The list is in ~/.mcp-stealth/window-state/<instance>-tabs.json, one entry per profile, readable by you only. Page URLs can carry tokens. browser_close(forget_tabs=True) and close_instance(instance_id, forget_tabs=True) close without saving and remove the list. profile_cleanup(action="remove_fallback", ...) removes the list of the profile it deletes. Deleting the file removes all of them.

Chrome 158 and saved logins (macOS)

Chrome 158 on macOS encrypts with a new key in any profile outside its own default folder, which is every profile this server uses. It does not read the cookies Chrome 157 stored there, and deletes them. The server moves them first, once per profile, the first time Chrome 158 or newer opens it:

1. It copies the profile's cookie databases aside, then opens the profile headless with --disable-features=KeychainKeyProviderUserDataDirProtection, which keeps the old cookies readable, and reads every cookie.
2. It writes them to ~/.mcp-stealth/storage-states/pre-v11-migration-<profile>-<time>.json, readable by you only. storage_state_load accepts that file.
3. It closes that Chrome, starts the launch you asked for normally, sets the cookies again, and reads them back.

The launch result says migrated N cookies to Chrome 158 encryption; backup at <path>. If fewer come back, the launch result is an error that names the missing cookies and the backup, and the next launch tries again. If anything fails before the backup is complete, that launch keeps the protection turned off so nothing is lost, and the next launch tries again. If Chrome reads fewer cookies than the profile holds, the copied databases are put back. Measured with Chrome Beta 158 standing in for Chrome 158, on profiles made by Chrome 157.

Only cookies move. Saved passwords, card and address data and other values Chrome 157 encrypted in that profile stay unreadable to Chrome 158 there. Only the profile folder being launched is moved (Default, or the one --profile-directory names). A profile in Chrome's own default folder keeps the old key and is left alone. A profile Chrome 158 has opened is refused to Chrome 157.

Two kinds of profile get left behind: privacy-profiles/<name>, when a server stops before it could delete one, and profile-pid<N>, which a server uses when another one holds profile/. A few seconds after it starts, the server checks both on a background thread and removes a folder only when all of these hold:

• ✅ It is a real folder directly in its place, with exactly that name, not a link.
• ✅ No Chrome holds its lock, no running program names it, and this server does not use it.
• ✅ Nothing in it changed in the last 10 minutes.
• ✅ For profile-pid<N>: the server with PID N has ended, and the profile holds none of these: cookies, saved passwords, history, autofill or cards, top sites, saved tabs, local storage, IndexedDB, extensions, bookmarks. A file it cannot read counts as holding something.

It never touches profile/, profiles/, app/ or anything else. server_status shows what the last run removed and what it kept, under profile_gc. A profile-pid<N> that holds something stays: profile_report lists what is in each one (counts and cookie domains, no values), and profile_cleanup(action="remove_fallback", names=[...], confirm=True) removes the ones you name. Removal is permanent.

What tool results tell you

Results describe what was observed. A tool that reports success when nothing happened would leave an agent building on a false result, so these rules hold across the server:

• ✅ Clicks are real mouse input. click, click_text, click_role, click_element_offset, click_at_corner and hover test the target first and refuse by name when something covers it. Clicks say clicked but NO page change detected when nothing happened, and name any new tab the click opened. A JS click only happens with js_fallback=True, and the result says so.
• ✅ A click is checked as soon as it lands and reported when the page changes, about 160 ms for a button that works. Only a click that changes nothing waits the full 450 ms before saying so, so a handler that reacts after 300 ms is not reported as dead.
• ✅ The hit test before a click and the before and after comparison run in an isolated world, like the snapshot. A page that replaces getBoundingClientRect, elementFromPoint, getComputedStyle or querySelector to watch for automation sees none of them called by a click, a hover or a navigation: 0 calls, where one click used to make 37.
• ✅ A native dialog cannot hang the server. A click, key or pointer move that opens one returns and names it, any other tool that needs the page says so instead of waiting, and dialog_handle answers the one already open.
• ✅ select_option sets the value from JS because a native dropdown cannot be driven with page input. The result states isTrusted=false, and the value is read back.
• ✅ browser_snapshot writes nothing to the page. Refs live on the server and reach into iframes, cross-origin ones included, and open shadow roots. A field shows its label as label="...", taken from <label for>, a label around it or aria-labelledby, and name_contains finds it by that. The label's own row is left out when its field is listed, and the count of those rows is reported.
• ✅ navigate reports the final URL, redirects, status and ready state, and waits for the load event up to 15 seconds. expect_url and expect_status turn a redirect into a failure. A page that did not load is an error, and batch_actions and workflow_run count it as failed. It no longer raises the window unless you pass focus=True.
• ✅ A visible browser stays behind the app you are using. browser_launch, spawn_browser, tab_new, tab_select and page actions do not take the keyboard, measured with lsappinfo on macOS. tab_new opens its own background window, or with new_window=False a tab behind the one its window shows, which pages still read as visible (Chrome picks the window and the result names it). tab_select only changes which tab tools act on unless you pass focus=True, and says when the page it selected reads as hidden. A click that calls window.open still brings Chrome forward for about 130 ms before focus returns, so keys typed in that moment reach Chrome. tab_focus raises the window on request. Quitting it with Cmd+Q or the Dock, or closing all its windows, ends it within about 3.5 seconds, also when the server that launched it has exited or was reinstalled meanwhile: each visible browser has a small watcher process of its own. The next tool call says it was closed, and nothing starts it again by itself. Closing the last tab with tab_close does not count as a Quit.
• Own Dock icon (macOS, opt-in): with MCP_STEALTH_DOCK_ICON=1, a visible browser on a new profile runs from Google Chrome Beta (/Applications/Google Chrome Beta.app) with the project icon, so it is not mistaken for your own Chrome. It needs Chrome Beta installed. Measured on Chrome Beta 158:
  • Only a profile nothing has written to goes to Beta: persistent=False, privacy=True, or a profile folder that does not exist yet or is empty. A profile that already holds data stays on Google Chrome and the result says why. Chrome 158 does not read the v10 cookies Chrome 157 stores in a profile outside its default folder, and deletes them: a copy of a profile with 1172 cookies had none left after Beta opened it. When in doubt, Google Chrome is used.
  • A profile Beta made stays on Beta, and the result says so. Google Chrome 157 is refused it, headless too, until Google Chrome reaches the version that last opened it.
  • The icon is a custom Finder icon at the top of the Beta app (Icon\r and a Finder flag). Nothing inside Contents/ changes, and codesign --verify --deep still passes. An update of Beta removes the icon. The next visible launch puts it back in the background, about 0.3 seconds, and does not wait for it. /Applications/Google Chrome.app is never changed.
  • Beta registers with Google's updater under its own entry, com.google.chrome.beta. The com.google.chrome entry is not changed. Headless browsers, attach_to_chrome and the solve_turnstile_oscursor helper keep Google Chrome. The helper stops at once when the main browser runs a different Chrome version, because a clearance bound to the user agent could not be moved over.
  • server_status reports dock_icon: off, beta-ready, beta-missing, icon-missing or unavailable, with the reason.
  • The Chrome copy used by 0.13.0 is gone. A copy left in ~/.mcp-stealth/app is removed when a server starts and no browser runs from it.
• ✅ A profile last opened by a newer Chrome is never opened by an older one. The launch is refused with both versions named, nothing starts, and the profile is not changed. The version is read from Last Version and Local State in the profile. An older Chrome can damage a profile a newer one has upgraded.
  • It needs macOS with the copy on the same APFS volume as Chrome. If the copy cannot be made, launches use Chrome itself and the result says why. Headless launches and attach_to_chrome are not affected.
• ✅ evaluate, frame_evaluate and wait_for_function report a JavaScript exception as an error, and promises are awaited. Objects and arrays come back as JSON.
• ✅ type_text, humanize_type and fill send a keydown and keyup per character. type_text refuses when no field has focus, and refuses a newline in a single-line field.
• ✅ upload_file refuses a path that is not a file. paste_text refuses a field that cannot take text and reports what landed, contenteditable included.
• ✅ click_turnstile, verify_cf and auto_verify report what the page shows after the click: whether the token filled, the title, and whether the challenge is still there. A click alone is not a pass, and no click happens when no checkbox matched. A challenge still present names solve_turnstile_oscursor as the next step.
• ✅ press_key reports what the key did: navigation, page change, focus, or nothing.
• ✅ fill_form fails when a field fails and then does not submit. batch_actions counts it as failed.
• ✅ Empty results say whether anything was measured. console_get, intercept_log and storage_snapshot report that state, and network_get is an error before network_start.
• ✅ assert_clickable tells you what would block a click without clicking.
• ✅ A lost browser connection names the condition and how to recover. browser_recover handles a stuck browser and only touches this server's profiles.

✅ Credentials stay out of tool output, since output lands in the agent's transcript. cookie_list, network_get, intercept_log, wait_for_request, auth_capture, export_curl, http_request and http_request_with_session hide cookies, credential headers, JSON and form fields, and query parameters unless you pass reveal_values=True. Bodies in other formats pass through unchanged. export_curl also returns an http_request call that replays the session with the browser's own cookies. Files holding credentials are written mode 600.

Tools

Open a group to see its tools.

Main features

API keys

✅ 167 of the 173 tools need no key. These six do:

solve_recaptcha_ai suits low volume with your own key. solve_captcha suits production, since a dedicated service handles more challenge types.

Add the key to the env block of the server config. Use one of these:

"env": { "OPENAI_API_KEY": "sk-...", "OPENAI_MODEL": "your-vision-model" }
"env": { "ANTHROPIC_API_KEY": "sk-ant-...", "ANTHROPIC_MODEL": "your-vision-model" }
"env": { "OPENAI_BASE_URL": "https://api.groq.com/openai/v1", "OPENAI_API_KEY": "gsk_...", "OPENAI_MODEL": "your-vision-model" }
"env": { "OPENAI_BASE_URL": "http://localhost:11434/v1", "OPENAI_API_KEY": "ollama", "OPENAI_MODEL": "your-local-vision-model" }
"env": { "CAPSOLVER_KEY": "CAP-..." }

• ✅ Works: any current model that accepts images
• ❌ Fails: text-only models

Always set the model name. The built-in fallback may be out of date.

Any provider with /v1/chat/completions and image_url support works.

Order of use: arguments to the tool, then OPENAI_*, then AI_VISION_* (deprecated, it logs a warning), then ANTHROPIC_*.

One server for many clients

By default each client starts its own server over stdio. With --http, one server handles them all, and each connection (Mcp-Session-Id) gets its own instances, tabs and logs. Another session's instance is refused until that session calls instance_release.

mcp-stealth-chrome --http                # http://127.0.0.1:8765/mcp

The server can act as whoever is logged in to its browsers, so access is restricted:

• ✅ A bearer token is always required, from MCP_STEALTH_TOKEN or ~/.mcp-stealth/http-token (created mode 600 on first run, never printed). Send it as Authorization: Bearer <token>.
• ✅ Only loopback is allowed unless you pass --allow-remote. The token then travels unencrypted without a TLS proxy. Behind a proxy or on a wildcard address, name what clients use with --allowed-host.
• ✅ Host and Origin checks stay on, which blocks DNS rebinding from a web page.

Things to know:

• A second session's default browser gets its own profile without the first session's logins. Use instance_release or clone_chrome_profile to share.
• Subagents on one connection count as one session and share state.
• Each session runs its own Chrome, so this saves server processes and not browser memory.
• When a client ends its session, its browsers wait to be claimed or closed by the idle timeout.
• Request interception and performance tracing work for one session at a time.

Environment variables

Development

git clone https://github.com/RobithYusuf/mcp-stealth-chrome
cd mcp-stealth-chrome
uv sync
uv run mcp-stealth-chrome                # stdio server
uv run pytest tests/ -q                  # fast tests
MCP_E2E=1 uv run pytest tests/ -q        # adds the real Chrome tests

CI runs the fast tests on macOS, Ubuntu and Windows with Python 3.11 and 3.13, installs the built wheel without uv.lock and calls server_status through a real MCP client, and runs the real Chrome tests headless on all three. Tests that need a visible window or Chrome Beta run only on a developer's Mac.

AGENTS.md records the rules and platform facts behind the code.

Related

mcp-camoufox offers the same tool names and snapshot format on Firefox, for sites where Chromium is harder to get through.

Built with nodriver, curl_cffi, FastMCP and OpenCV. stealth-browser-mcp covers UI cloning and network hooks.

License

MIT. See LICENSE.