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 86 tools: every Playwright MCP tool except (see ), plus a Cloak-exclusive stealth/profile/audit layer.
Playwright-compatible MCP server on CloakBrowser stealth Chromium: 86 tools, humanized input.
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/.
Requires Node.js ^20.19.0 || >=22.12.0 (the minimum CloakBrowser itself needs).
The binary comes in two tiers. Without a key you get the free binary. Set CLOAKBROWSER_LICENSE_KEY in the MCP server's environment to use a CloakBrowser Pro license; CLOAKBROWSER_RELEASE_CHANNEL (stable or preview) and CLOAKBROWSER_VERSION are read by the CloakBrowser library too. See cloakbrowser.dev for what each tier includes. cloak_binary_info reports the active tier.
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.
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_find
text or regex
filename
Searches the snapshot instead of returning all of it. Each match is shown under its path from the root with a few lines of context, up to 20 matches. regex is case-sensitive unless written as /pattern/i.
browser_emulate_media
—
colorScheme, reducedMotion, forcedColors, contrast, media
Omitted parameters are left unchanged; null clears an override back to the system setting.
browser_take_screenshot
—
element, target, type, fullPage, quality, saveAs
Image is returned inline; optionally saved to disk.
browser_annotate from Playwright MCP is not provided. It opens Playwright's dashboard window and waits for a person to draw on the page, and Playwright runs that as an internal process that this server does not launch.
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
You: Open https://saas.example.com, sign in as [email protected] / <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.
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):
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.
Upgraded cloakbrowser from 0.3.x to 0.6.3. The new releases add Pro licensing, release channels, and signed download verification. Nothing the server used was removed. No new MCP tools; the tool count stays at 80.
Fix: library log lines could corrupt the stdio stream.cloakbrowser reports some events (for example auto-encoding of special characters in proxy credentials) with console.info, which Node writes to stdout, where an MCP client expects only JSON-RPC. console.log, console.info and console.debug are now routed to stderr while the server runs.
Node requirement is now ^20.19.0 || >=22.12.0 (was declared as >=18). CloakBrowser 0.3.30 already required Node 20 or newer, and 0.6.x needs 20.19 or newer. CI no longer tests Node 18.
Six tools added for parity with Playwright MCP 0.0.83 (80 → 86):
browser_find — search the snapshot for text or a regex.
browser_emulate_media — color scheme, reduced motion, forced colors, contrast, media type. null clears an override.
browser_video_show_actions / browser_video_hide_actions (devtools) — annotate actions on the page while recording or screencasting.
browser_start_recording / browser_stop_recording (devtools) — record what the user does in the browser and return it as Playwright code.
browser_annotate is not provided: it launches Playwright's internal dashboard process and needs someone to draw on the page.
playwright-core minimum raised to ^1.61.0, the first release with page.screencast.showActions(); the resolved version moves from 1.60.0 to 1.64.1.
Input schemas now advertise nullable parameters as { oneOf: [<type>, null] } (the converter used to drop the null), which browser_emulate_media needs.
Added mcpName to package.json and a server.json for the official MCP Registry, including the optional CLOAKBROWSER_LICENSE_KEY variable.
[0.1.4] - 2026-08-23
Fix: browser_evaluate without target always failed. The function was passed to Playwright as a string expression, so the function object came back instead of its result, which serialized to undefined and failed MCP result validation. It is now invoked, and a function that legitimately returns undefined reports the string "undefined".
[0.1.3] - 2026-08-23
Fix: a failed browser launch could not be retried. A rejected launch promise was cached and re-awaited forever, so one transient error forced a process restart. It is now cleared on failure.
Clearer errors. A stale CloakBrowser process holding the profile directory used to surface as "No active page". There is now a NO_BROWSER error (BrowserNotLaunchedError) that carries the underlying launch error and the command to find stale processes, and a TAB_NOT_FOUND error for an unknown tab id. NoActivePageError no longer tells the caller to run the call that is itself failing.
[0.1.2] - 2026-08-03
No behaviour change. Release-pipeline only: publishes via npm trusted publishing (OIDC) instead of an NPM_TOKEN secret. A long-lived token expires silently, and npm answers an unauthorized publish with 404 Not Found - PUT — which reads like a missing package rather than an auth failure. OIDC has nothing to expire.
Dropped registry-url from actions/setup-node: it writes an .npmrc containing _authToken=${NODE_AUTH_TOKEN} and, with no token supplied, exports NODE_AUTH_TOKEN as the literal placeholder XXXXX-XXXXX-XXXXX-XXXXX, so npm authenticates with a bogus token instead of falling through to OIDC.
The release job pins npm to the 11.x line before publishing — OIDC needs >= 11.5.1 and Node 22 still bundles 10.x. Provenance is automatic under trusted publishing, so the explicit --provenance flag is gone; attestation coverage is unchanged.
[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.