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.

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.

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

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 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.
• ✅ 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, and tab_select only changes which tab tools act on unless you pass focus=True. 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 closing all its windows, ends it within a few seconds, and the next tool call says so.
• ✅ 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

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.