cloakbrowser-mcp
cloakbrowser-mcp is a drop-in Playwright MCP-compatible browser automation server with unchanged upstream tools, CloakBrowser Chromium, and production-ready npm, Docker, and Streamable HTTP packaging. It runs upstream @playwright/mcp as the canonical tool surface and points that runtime at CloakBrowser.
30-second demo
Run npx -y cloakbrowser-mcp@latest, connect Claude Desktop or Codex CLI, ask for web research, daily automation, or testing in plain English, and inspect the real browser result.
Documentation: swimmwatch.github.io/cloakbrowser-mcp · Comparison · Recipes
Use it when you need:
- Playwright MCP browser automation backed by CloakBrowser;
- unchanged upstream browser tools plus two local introspection tools;
- npm or Docker installation over stdio or Streamable HTTP;
- opt-in, session-scoped managed CDP access for
CDP-capable clients through
chromium.connectOverCDP(); - persistent browser profiles, validated context options, and Chrome extension loading;
- GeoIP-aware proxy matching for regional QA;
- humanized mouse, keyboard, and scroll behavior for interaction-sensitive flows.
Cross-platform checks cover npm on Linux x64/arm64, macOS arm64/x64, and Windows x64 across the Node.js versions listed in Testing. Docker images are built and smoke-tested for linux/amd64 and linux/arm64.
See @playwright/mcp vs cloakbrowser-mcp when deciding whether plain upstream Playwright MCP or CloakBrowser MCP fits a deployment better. The Recipes pages show task-focused setup paths for persistent login profiles, Chrome extensions, reverse proxies, regional QA, client connections, and CI smoke tests.
Install With npm
npx -y cloakbrowser-mcp@latest
Requires Node.js 22.13+ in the 22.x line, or Node.js 24+. Run diagnostics before wiring a client:
npx -y cloakbrowser-mcp@latest doctor
For Streamable HTTP instead of stdio:
npx -y cloakbrowser-mcp@latest --transport streamable-http --http-port 3000
See the generated CLI Reference for all flags.
Install With Docker
docker run --rm -i \
-v "$PWD/artifacts:/data" \
swimmwatch/cloakbrowser-mcp:latest
For Streamable HTTP:
docker run --rm -p 127.0.0.1:3000:3000 \
-v "$PWD/artifacts:/data" \
swimmwatch/cloakbrowser-mcp:latest \
--transport streamable-http --http-host 0.0.0.0 --http-port 3000
The Docker image writes artifacts to /data and is published for linux/amd64 and linux/arm64. It defaults to CLOAK_PLAYWRIGHT_MCP_NO_SANDBOX=true for compatibility with containerized runtimes where Chromium sandboxing is often unavailable. If your host and container runtime support Chromium sandboxing, set CLOAK_PLAYWRIGHT_MCP_NO_SANDBOX=false; for untrusted pages, keep container network access and mounted host directories tightly scoped. The same tags are also available from ghcr.io/swimmwatch/cloakbrowser-mcp. See Docker for persistent profiles, extension mounts, HTTPS, and smoke-test examples, or use the reverse proxy recipe for a focused Streamable HTTP deployment.
Add To MCP Clients
Codex CLI
codex mcp add cloakbrowser -- npx -y cloakbrowser-mcp@latest
Claude Code
claude mcp add --transport stdio cloakbrowser -- npx -y cloakbrowser-mcp@latest
GitHub Copilot In VS Code
{
"servers": {
"cloakbrowser": {
"type": "stdio",
"command": "npx",
"args": ["-y", "cloakbrowser-mcp@latest"]
}
}
}
Claude Desktop, Cursor, Cline, Windsurf, Warp, And Other mcpServers Clients
Add this server entry to the client's MCP JSON config:
{
"mcpServers": {
"cloakbrowser": {
"command": "npx",
"args": ["-y", "cloakbrowser-mcp@latest"]
}
}
}
Docker-backed stdio
{
"mcpServers": {
"cloakbrowser": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-v",
"/tmp/cloakbrowser-artifacts:/data",
"swimmwatch/cloakbrowser-mcp:latest"
]
}
}
}
Already-running Streamable HTTP server
npx -y cloakbrowser-mcp@latest --transport streamable-http --http-port 3000
codex mcp add cloakbrowser --url http://127.0.0.1:3000/mcp
claude mcp add --transport http cloakbrowser http://127.0.0.1:3000/mcp
Prompt For A Code Assistant
Paste this into Codex, Claude Code, Copilot, Cursor, Cline, Windsurf, or a similar coding assistant that can edit MCP config:
Install the CloakBrowser MCP server for this workspace. Name it "cloakbrowser".
Prefer stdio with command "npx" and args ["-y", "cloakbrowser-mcp@latest"].
If this client uses VS Code mcp.json, add it under "servers" with type "stdio".
If this client uses Claude/Cursor/Cline/Windsurf/Warp-style config, add it under
"mcpServers" with the same command and args. Do not add secrets.
More examples are in Getting Started, with dedicated recipes for Claude Desktop and Codex CLI.
Configuration
Use upstream PLAYWRIGHT_MCP_* variables for browser, artifacts, timeouts, network, and tool capability settings. Cloak-specific bridge toggles use CLOAK_PLAYWRIGHT_MCP_*. Select a Pro Preview browser build before startup with --release-channel preview or CLOAK_PLAYWRIGHT_MCP_RELEASE_CHANNEL=preview; the default is stable.
The common variable table now lives in Configuration. That page also covers persistent profiles, validated context options, Chrome extensions, Streamable HTTP metadata, and HTTPS/auth options. See GeoIP Proxy Matching for regional proxy behavior, Humanized Input Behavior for interaction realism, and Recipes for task-focused configurations.
Version Compatibility
See Version Compatibility for the maintained compatibility table.
Tools
The upstream Playwright MCP tool list is authoritative. This project does not reimplement or re-document upstream browser schemas in source code.
Local tools:
cloakbrowser_binary_inforeturns CloakBrowser package, platform, cache, and resolved binary data.cloakbrowser_bridge_inforeturns bridge metadata, upstream package/version, and local tool names.
Development
npm install
npm run build
npm test
npm run docker:build
npm run docker:smoke
npm run server:validate
npm run bridge:compare -- cloakbrowser-mcp:dev --report bridge-parity-report.json
Documentation starts at docs/getting-started.md. Contributor material is grouped under docs/contributor-guide.md.
See test reporting for local Allure reports and combined CI matrix reports linked from pull requests.
