cloak-browser-mcp

A Model Context Protocol (MCP) server backed by CloakHQ/CloakBrowser — a source-patched Chromium that passes Cloudflare Turnstile, reCAPTCHA v3, FingerprintJS, BrowserScan, and 30+ other bot detection services without runtime JS injection.

Drop-in replacement for @playwright/mcp with 80 tools: full Playwright-MCP parity plus a Cloak-exclusive stealth/profile/audit layer.

Works with Claude Code, Cursor, VS Code, Codex, Gemini CLI, Windsurf, or any MCP client.

Why CloakBrowser over vanilla Playwright?

	`@playwright/mcp`	`cloak-browser-mcp`
Chromium	Stock	Source-patched (58 C++ patches)
`navigator.webdriver`	`true` (leaks)	absent
Cloudflare Turnstile	Fails	Auto-pass
reCAPTCHA v3 score	~0.1	~0.9
Humanized mouse / keyboard	None	Bézier curves, typo correction
Persistent profiles	Manual	First-class CLI flag + management tools
GeoIP-aware emulation	None	Auto timezone/locale from proxy exit IP
Stealth audit / detection probe	None	Built-in `cloak_stealth_audit` + `cloak_detection_test`

When you don't need stealth, @playwright/mcp is faster and lighter — use that. When the site has any bot detection (Cloudflare, DataDome, PerimeterX, FingerprintJS) — use this.

Quick start

1. Install once

The wrapper installs from npm; the CloakBrowser Chromium binary (~200 MB) downloads on first use into ~/.cloakbrowser/.

npm install -g @devinwangd/cloak-browser-mcp

Or run on demand without installing:

npx @devinwangd/cloak-browser-mcp --caps all

After install, the binary on PATH is cloak-browser-mcp (unscoped) — that's what you reference in MCP client configs below.

2. Wire into your MCP client

Claude Code (`~/.claude.json` or project `.mcp.json`)

{
  "mcpServers": {
    "cloak-browser": {
      "command": "cloak-browser-mcp",
      "args": ["--caps", "all"]
    }
  }
}

Cursor / VS Code (`.cursor/mcp.json` or `.vscode/mcp.json`)

{
  "servers": {
    "cloak-browser": {
      "command": "cloak-browser-mcp",
      "args": ["--caps", "all"]
    }
  }
}

Persistent profile + proxy + humanized inputs

{
  "mcpServers": {
    "cloak-browser": {
      "command": "cloak-browser-mcp",
      "args": [
        "--caps", "all",
        "--profile-dir", "/Users/me/.cloak-browser-mcp/profiles/work",
        "--proxy", "http://user:pass@proxy.example.com:8080",
        "--timezone", "Europe/London",
        "--locale", "en-GB",
        "--geoip",
        "--humanize",
        "--viewport", "1920x1080",
        "--allowed-domains", "*.example.com,*.cloudflare.com"
      ]
    }
  }
}

3. Use it

In Claude Code:

"Open example.com, click the search box, search for 'hello', take a screenshot."

The agent will call browser_navigate → browser_snapshot → browser_click → browser_type → browser_take_screenshot.

Capabilities (`--caps`)

Cap	Tools	Use when
(always)	navigation, interaction, page state	Standard browsing
`network`	request inspection, route mocking, offline simulation	Debugging APIs, testing failure modes
`storage`	cookies, localStorage, sessionStorage, storage state export/import	Auth state persistence, session replay
`vision`	pixel-coordinate mouse	Bypassing accessibility tree for canvas / SVG apps
`pdf`	`browser_pdf_save`	Snapshotting pages as PDF
`testing`	`verify_*` + `generate_locator`	Codegen for Playwright tests
`devtools`	highlight, tracing, video, resume	Debugging agent decisions
`config`	`get_config`, `close`, `run_code_unsafe`	Introspection + (with `--enable-unsafe-eval`) arbitrary JS
`humanize`	`cloak_humanize_set`	Tuning humanized input parameters

--caps all enables everything (except run_code_unsafe, which additionally requires --enable-unsafe-eval).

CloakBrowser-exclusive tools (always on)

Tool	Purpose
`cloak_set_fingerprint`	Override canvas seed, GPU vendor/renderer, screen size, hardware concurrency, device memory, UA brand, platform, storage quota
`cloak_set_timezone`	Live timezone via CDP (no relaunch)
`cloak_set_locale`	Override `navigator.language` and `Accept-Language`
`cloak_set_geolocation`	Set coords, or auto-resolve from proxy exit IP
`cloak_set_proxy`	Switch proxy mid-session
`cloak_detection_test`	Load a known probe (CreepJS, FingerprintJS, BrowserScan, SannySoft, Cloudflare Turnstile) and dump results
`cloak_stealth_audit`	Programmatic check: `navigator.webdriver`, plugin count, WebGL vendor, languages, UA, chrome.runtime, canvas hash, `$cdc_*` CDP signals
`cloak_request_signal_inspect`	Capture per-request TLS / header signals for a single URL
`cloak_persistent_profile_create` / `list` / `delete`	Manage `~/.cloak-browser-mcp/profiles/`
`cloak_binary_info` / `cloak_binary_update`	Inspect / refresh the CloakBrowser Chromium binary

CLI flags

Flag	Value	Default	Notes
`--caps <csv>`	`all` or any subset	(none)	Enables capability-gated tools
`--profile-dir <path>`	Absolute path	(ephemeral)	Persistent user-data dir
`--headless` / `--headed`	(boolean)	headed (visible)	Pass `--headless` for batch/CI runs.
`--proxy <url>`	http(s)/socks5 with inline auth	none
`--timezone <tz>`	IANA tz	system	e.g. `America/New_York`
`--locale <bcp47>`	BCP-47	system	e.g. `en-US`
`--user-agent <ua>`	string	(cloak default)
`--viewport <WxH>`	e.g. `1920x1080`	1280×720
`--geoip`	boolean	off	Auto resolve geolocation from proxy IP
`--humanize`	boolean	off	Enable Bézier mouse + typo-correcting keyboard
`--fingerprint-seed <int>`	int	random	Deterministic canvas/WebGL noise
`--allowed-domains <csv>`	host patterns	(open)	Whitelist for `browser_navigate`
`--blocked-domains <csv>`	host patterns	(none)	Blocklist for `browser_navigate`
`--enable-unsafe-eval`	boolean	off	Required for `browser_run_code_unsafe`
`--upload-allow-dir <path>`	path	(none)	Restrict file-upload source paths
`--download-dir <path>`	path	(cwd)	Where downloaded files land
`--max-pages <n>`	int	20	Concurrent tab cap
`--self-test`	boolean	off	Print the tool list and exit

Tool inventory

Tools are grouped by capability. The "always-on" sections are exposed regardless of --caps; capability-gated sections require the matching --caps entry.

Always-on

Navigation

Tool	Required	Optional	Notes
`browser_navigate`	`url`	`waitUntil`, `timeoutMs`	Subject to `--allowed-domains` / `--blocked-domains`. Returns a fresh `[eN]` snapshot.
`browser_navigate_back`	—	—	History back in the active tab.
`browser_tabs`	`action` (`list`/`new`/`switch`/`close`)	`index`, `id`, `url`	Manage tabs by id (`t1`,…) or 0-based index.

Interaction

Tool	Required	Optional	Notes
`browser_click`	`target`	`element`, `doubleClick`, `button`, `modifiers`	`target` is a `eN` ref or a Playwright selector.
`browser_type`	`target`, `text`	`element`, `submit`, `slowly`	`slowly:true` triggers per-character typing; combine with `--humanize`.
`browser_hover`	`target`	`element`
`browser_drag`	`startTarget`, `endTarget`	`startElement`, `endElement`
`browser_drop`	`target`	`paths`, `data`	File paths via `setInputFiles`; arbitrary MIME data via synthetic DataTransfer.
`browser_select_option`	`target`, `values`	`element`
`browser_press_key`	`key`	—	Page-level key press (e.g. `Control+A`, `ArrowDown`).
`browser_handle_dialog`	`accept`	`promptText`	Responds to the most recently captured dialog.
`browser_file_upload`	`paths`	—	Paths constrained by `--upload-allow-dir` if set.
`browser_fill_form`	`fields`	—	Each field has `target` + `value` (+ optional `kind`).
`browser_scroll`	—	`target`, `direction`, `amount`	Element-scoped or page-level.

Page state

Tool	Required	Optional	Notes
`browser_snapshot`	—	—	Accessibility tree with `[eN]` refs for interactable nodes.
`browser_take_screenshot`	—	`element`, `target`, `type`, `fullPage`, `quality`, `saveAs`	Image is returned inline; optionally saved to disk.
`browser_console_messages`	—	`level`, `limit`	Buffered console + pageerror.
`browser_wait_for`	—	`timeMs`, `text`, `textGone`, `selector`, `state`, `timeoutMs`
`browser_resize`	`width`, `height`	—
`browser_evaluate`	`function`	`element`, `target`	Function source must be an arrow or function expression.

CloakBrowser-exclusive

Tool	Required	Optional	Notes
`cloak_set_fingerprint`	—	`seed`, `gpuVendor`, `gpuRenderer`, `screenWidth`, `screenHeight`, `hardwareConcurrency`, `deviceMemoryGB`, `uaBrand`, `uaBrandVersion`, `platform`, `storageQuotaMB`	Some flags only take effect on next launch — call `browser_close` then any tool to relaunch.
`cloak_set_timezone`	`timezone`	—	Live via CDP.
`cloak_set_locale`	`locale`	—	Sets navigator.language + Accept-Language header.
`cloak_set_geolocation`	—	`latitude`, `longitude`, `accuracy`, `fromProxyIp`	`fromProxyIp` calls ipapi.co/json/ via current proxy.
`cloak_set_proxy`	`proxy`	—	Recreates the context.
`cloak_detection_test`	—	`suite`, `customUrl`	Suites: `creepjs`, `fingerprintjs`, `browserscan`, `sannysoft`, `cloudflare-turnstile`.
`cloak_stealth_audit`	—	—	Programmatic audit.
`cloak_request_signal_inspect`	`url`	—	Returns TLS details, response status, request headers, response headers.
`cloak_persistent_profile_create`	`name`	—	Creates `~/.cloak-browser-mcp/profiles/<name>`.
`cloak_persistent_profile_list`	—	—
`cloak_persistent_profile_delete`	`name`, `confirm=true`	—
`cloak_binary_info`	—	—
`cloak_binary_update`	—	—

Capability-gated

--caps network — browser_network_requests, browser_network_request, browser_route, browser_route_list, browser_unroute, browser_network_state_set.

--caps storage — browser_cookie_set/get/list/delete/clear, browser_localstorage_*, browser_sessionstorage_*, browser_storage_state, browser_set_storage_state.

--caps vision — browser_mouse_click_xy, browser_mouse_move_xy, browser_mouse_drag_xy, browser_mouse_down, browser_mouse_up, browser_mouse_wheel.

--caps pdf — browser_pdf_save.

--caps testing — browser_verify_element_visible, browser_verify_text_visible, browser_verify_list_visible, browser_verify_value, browser_generate_locator.

--caps devtools — browser_highlight, browser_hide_highlight, browser_start_tracing, browser_stop_tracing, browser_start_video, browser_stop_video, browser_video_chapter, browser_resume.

--caps config — browser_get_config, browser_close, browser_run_code_unsafe (also needs --enable-unsafe-eval).

--caps humanize — cloak_humanize_set.

Target syntax for interaction tools

The target argument accepts:

eN ref from a prior browser_snapshot — e.g. e7. Most reliable.
CSS selector — e.g. button.primary.
xpath=… — e.g. xpath=//button[contains(., "Submit")].
text=… — e.g. text=Sign in.
role=…[name="…"] — e.g. role=button[name="Submit"].

After any navigation or significant DOM mutation, call browser_snapshot again to refresh refs.

Example flows

1. Take a screenshot of a Cloudflare-protected page

You: Open https://example-cloudflare-protected.com, wait for the page to settle, take a full-page screenshot.

Agent calls:
  browser_navigate(url="https://...")
  browser_wait_for(textGone="Checking your browser")
  browser_take_screenshot(fullPage=true)

Vanilla @playwright/mcp fails the Turnstile check; cloak-browser-mcp passes it automatically because the stealth patches are below the JS layer.

2. Sign into a SaaS dashboard, persist auth, reopen later

Phase 1 — initial sign-in with a fresh profile:

// .mcp.json
{
  "mcpServers": {
    "cloak": {
      "command": "cloak-browser-mcp",
      "args": [
        "--caps", "all",
        "--profile-dir", "/Users/me/.cloak-browser-mcp/profiles/saas-prod",
        "--humanize"
      ]
    }
  }
}

You: Open https://saas.example.com, sign in as me@example.com / <password>, then confirm I'm on the dashboard.

Phase 2 — reopen later, all cookies still present:

You: Open https://saas.example.com — you should already be signed in from yesterday's session.

3. Probe how stealth is doing

You: Run a stealth audit and then load the SannySoft bot detection test.

Agent:
  cloak_stealth_audit()
  cloak_detection_test(suite="sannysoft")

You'll see all green if stealth is intact.

4. Switch geolocation/timezone mid-session via proxy

You: Switch to a UK proxy, align my timezone/locale/geo to match, then load a country-specific landing page.

Agent:
  cloak_set_proxy(proxy="http://uk-proxy.example.com:8080")
  cloak_set_timezone(timezone="Europe/London")
  cloak_set_locale(locale="en-GB")
  cloak_set_geolocation(fromProxyIp=true)
  browser_navigate(url="https://example.com/uk")

5. Mock an API response while testing a frontend

You: While loading example.com, return a fake 500 to /api/orders so I can verify the error state.

Agent:
  browser_route(pattern="**/api/orders", status=500, body='{"error":"simulated"}', contentType="application/json")
  browser_navigate(url="https://example.com")
  browser_take_screenshot()
  browser_unroute(pattern="**/api/orders")

6. Export storage state, replay in a fresh session

Agent:
  browser_storage_state(filename="/tmp/saas-state.json")
  # …later, in a new ephemeral session…
  browser_set_storage_state(filename="/tmp/saas-state.json")
  browser_navigate(url="https://saas.example.com")

7. Run a Playwright trace for human review

You: Trace this whole flow so I can replay it in Playwright Trace Viewer.

Agent:
  browser_start_tracing(filename="/tmp/trace.zip", screenshots=true, snapshots=true)
  # …agent runs the flow…
  browser_stop_tracing()

You: open /tmp/trace.zip in Playwright Trace Viewer (https://trace.playwright.dev)

Security model

Read this before deploying on any machine that has production credentials.

TL;DR

Asset	Trust boundary
`cloak-browser-mcp` source (this repo)	MIT, public, audit by reading.
`cloakbrowser` npm package	Trust the CloakHQ maintainers + npm registry.
CloakBrowser Chromium binary	Downloaded on first use from `cloakbrowser.dev`. SHA-256 verified by upstream wrapper. The binary is closed-source by license.
Your env vars / Keychain / shell history	The MCP server inherits your process env. Do not run with prod credentials in scope unless you trust the supply chain.

Threats this package introduces

1. Supply-chain compromise

Three packages are pulled at install/run time: @modelcontextprotocol/sdk, playwright-core, and cloakbrowser + its downloaded Chromium binary. If CloakHQ's npm publish token or cloakbrowser.dev is compromised, an attacker could push a malicious binary that runs under your user account.

Mitigations:

Pin a known-good cloakbrowser version.
Set CLOAKBROWSER_BINARY_PATH to an audited binary.
Leave CLOAKBROWSER_SKIP_CHECKSUM at default (false).
Audit ~/.cloakbrowser/ and any --profile-dir you use.

2. Agent-driven browser navigation

By default browser_navigate accepts any URL. An LLM agent can be prompt-injected into navigating somewhere malicious.

Mitigations:

--allowed-domains <csv> (supports *.example.com).
--blocked-domains <csv> (checked first).
Use a dedicated ephemeral --profile-dir, not your real browser profile.
--max-pages <n> caps tab explosion.

3. Arbitrary JS execution

browser_evaluate — runs JS in the page sandbox. Cannot read your local filesystem. Always available.
browser_run_code_unsafe — runs JS in this Node.js server process. Can do anything Node can. Double-opt-in: needs --caps config AND --enable-unsafe-eval.

Mitigation: never combine --enable-unsafe-eval with a machine that has prod credentials in env vars.

4. File system reach

browser_file_upload and browser_drop can attach any file you have read access to. Use --upload-allow-dir <path> to restrict.

Write-side: browser_take_screenshot --saveAs, browser_pdf_save, browser_storage_state, browser_start_tracing write files at agent-chosen paths. If you don't want this, omit --caps pdf / storage / devtools.

5. Persistent profile leakage

A --profile-dir accumulates cookies/localStorage/IndexedDB. If synced to cloud storage, every site you've signed into via the agent becomes accessible to anyone with that sync token. Default path ~/.cloak-browser-mcp/profiles/<name> lives outside common cloud-sync roots.

6. Prompt-injection-driven exfil

A malicious page can prompt-inject the agent into navigating elsewhere with stolen state, or POST DOM secrets out. This is an LLM problem, not an MCP problem.

Use a separate session per task — browser_close between unrelated jobs.
Prefer ephemeral over persistent profiles for sensitive flows.
Review agent tool calls when the task touches anything authenticated.

7. Network egress

Call	Destination	When
CloakBrowser binary download	`cloakbrowser.dev` (override via `CLOAKBROWSER_DOWNLOAD_URL`)	First use after install
Browser traffic	Whatever the agent navigates to	Always
`cloak_set_geolocation --fromProxyIp`	`ipapi.co/json/`	Only when explicitly invoked

The wrapper does not phone home and does not collect telemetry.

Recommended deployment profiles

"Tight" (sensitive machine — has prod credentials):

--caps network,storage,pdf
--profile-dir /Users/me/.cloak-browser-mcp/profiles/scoped
--allowed-domains *.target.com
--upload-allow-dir /tmp/cloak-uploads
--max-pages 5

No --enable-unsafe-eval. No vision cap (xy clicks bypass allow-listing).

"Open" (research / personal browsing):

--caps all
--humanize
--max-pages 20

"Untrusted" (you don't fully trust the upstream binary yet) — run inside a Docker container or a fresh macOS user account with no Keychain access and no .env files mounted.

Reporting vulnerabilities

If you find a security issue in cloak-browser-mcp (not in the upstream cloakbrowser package or its binary): open a private security advisory at https://github.com/devinwang/cloak-browser-mcp/security/advisories/new.

For issues in upstream CloakBrowser: https://github.com/CloakHQ/CloakBrowser/security/advisories/new.

Changelog

[0.1.1] - 2026-05-24

BREAKING (UX): default is now headed (visible browser) instead of headless. An interactive MCP server should let the user watch the agent work. Pass --headless explicitly for batch/CI usage. Smithery default flipped to match.

[0.1.0] - 2026-05-24

Initial release. ~62 MCP tools backed by CloakHQ/CloakBrowser, covering full Playwright-MCP parity plus a Cloak-exclusive stealth/profile/audit/binary-management layer.
CLI: --caps, --profile-dir, --headless/--headed, --proxy, --timezone, --locale, --user-agent, --viewport, --geoip, --humanize, --fingerprint-seed, --allowed-domains, --blocked-domains, --enable-unsafe-eval, --upload-allow-dir, --download-dir, --max-pages, --self-test.
Smithery YAML for one-click integration.
MIT-licensed wrapper; upstream CloakBrowser Chromium binary remains proprietary-free-redistribute-prohibited.

License

Wrapper code: MIT (this package).
CloakBrowser Chromium binary: proprietary, free to use, no redistribution. See https://github.com/CloakHQ/CloakBrowser/blob/main/BINARY-LICENSE.md.

Acknowledgments

CloakHQ/CloakBrowser — the patched Chromium that does the real work.
@playwright/mcp — tool naming and accessibility-tree-first design inspired this server.
@modelcontextprotocol/sdk — the MCP plumbing.

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.github/workflows		.github/workflows
examples		examples
src		src
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
smithery.yaml		smithery.yaml
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

cloak-browser-mcp

Table of contents

Why CloakBrowser over vanilla Playwright?

Quick start

1. Install once

2. Wire into your MCP client

Claude Code (~/.claude.json or project .mcp.json)

Cursor / VS Code (.cursor/mcp.json or .vscode/mcp.json)

Persistent profile + proxy + humanized inputs

3. Use it

Capabilities (--caps)

CloakBrowser-exclusive tools (always on)

CLI flags

Tool inventory

Always-on

Navigation

Interaction

Page state

CloakBrowser-exclusive

Capability-gated

Target syntax for interaction tools

Example flows

1. Take a screenshot of a Cloudflare-protected page

2. Sign into a SaaS dashboard, persist auth, reopen later

3. Probe how stealth is doing

4. Switch geolocation/timezone mid-session via proxy

5. Mock an API response while testing a frontend

6. Export storage state, replay in a fresh session

7. Run a Playwright trace for human review

Security model

TL;DR

Threats this package introduces

1. Supply-chain compromise

2. Agent-driven browser navigation

3. Arbitrary JS execution

4. File system reach

5. Persistent profile leakage

6. Prompt-injection-driven exfil

7. Network egress

Recommended deployment profiles

Reporting vulnerabilities

Changelog

[0.1.1] - 2026-05-24

[0.1.0] - 2026-05-24

License

Acknowledgments

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Claude Code (`~/.claude.json` or project `.mcp.json`)

Cursor / VS Code (`.cursor/mcp.json` or `.vscode/mcp.json`)

Capabilities (`--caps`)

Packages