{ "markdown": "# cloakbrowser-mcp\n\n

\n \"CloakBrowser\n

\n\n[![CI](https://github.com/swimmwatch/cloakbrowser-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/swimmwatch/cloakbrowser-mcp/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/swimmwatch/cloakbrowser-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/swimmwatch/cloakbrowser-mcp)\n[![Actionlint](https://github.com/swimmwatch/cloakbrowser-mcp/actions/workflows/actionlint.yml/badge.svg)](https://github.com/swimmwatch/cloakbrowser-mcp/actions/workflows/actionlint.yml)\n[![CodeQL](https://github.com/swimmwatch/cloakbrowser-mcp/actions/workflows/codeql.yml/badge.svg)](https://github.com/swimmwatch/cloakbrowser-mcp/actions/workflows/codeql.yml)\n[![Dependency Review](https://github.com/swimmwatch/cloakbrowser-mcp/actions/workflows/dependency-review.yml/badge.svg)](https://github.com/swimmwatch/cloakbrowser-mcp/actions/workflows/dependency-review.yml)\n[![OpenSSF Scorecard](https://github.com/swimmwatch/cloakbrowser-mcp/actions/workflows/scorecard.yml/badge.svg)](https://github.com/swimmwatch/cloakbrowser-mcp/actions/workflows/scorecard.yml)\n[![Zizmor](https://github.com/swimmwatch/cloakbrowser-mcp/actions/workflows/zizmor.yml/badge.svg)](https://github.com/swimmwatch/cloakbrowser-mcp/actions/workflows/zizmor.yml)\n[![Release](https://github.com/swimmwatch/cloakbrowser-mcp/actions/workflows/release.yml/badge.svg)](https://github.com/swimmwatch/cloakbrowser-mcp/actions/workflows/release.yml)\n[![GitHub Release](https://img.shields.io/github/v/release/swimmwatch/cloakbrowser-mcp?logo=github&label=GitHub%20release)](https://github.com/swimmwatch/cloakbrowser-mcp/releases)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-published-2E8555)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.swimmwatch%2Fcloakbrowser-mcp)\n[![cloakbrowser-mcp MCP server](https://glama.ai/mcp/servers/swimmwatch/cloakbrowser-mcp/badges/score.svg)](https://glama.ai/mcp/servers/swimmwatch/cloakbrowser-mcp)\n[![Awesome MCP Servers](https://img.shields.io/badge/Awesome%20MCP%20Servers-listed-2E8555)](https://github.com/punkpeye/awesome-mcp-servers)\n[![npm](https://img.shields.io/npm/v/cloakbrowser-mcp.svg?logo=npm)](https://www.npmjs.com/package/cloakbrowser-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/cloakbrowser-mcp.svg?logo=npm&label=npm%20downloads)](https://www.npmjs.com/package/cloakbrowser-mcp)\n[![Docker Hub pulls](https://img.shields.io/docker/pulls/swimmwatch/cloakbrowser-mcp?logo=docker&label=Docker%20Hub)](https://hub.docker.com/r/swimmwatch/cloakbrowser-mcp)\n[![Docker image](https://img.shields.io/docker/v/swimmwatch/cloakbrowser-mcp?sort=semver&logo=docker&label=Docker%20image)](https://hub.docker.com/r/swimmwatch/cloakbrowser-mcp/tags)\n[![Node.js 22.13+ or 24+](https://img.shields.io/badge/Node.js-22.13%2B%20or%2024%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)\n[![TypeScript strict](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)](tsconfig.json)\n[![Cross-platform](https://img.shields.io/badge/Cross--platform-Linux%20%7C%20macOS%20%7C%20Windows-2563eb)](docs/version-compatibility.md)\n[![Available on CodeGuilds](https://img.shields.io/badge/Available_on-CodeGuilds-6366f1)](https://codeguilds.dev/packages/cloakbrowser-mcp)\n[![MCP Server](https://img.shields.io/badge/MCP-server-000000)](https://modelcontextprotocol.io/)\n[![MCP transports](https://img.shields.io/badge/MCP%20transports-stdio%20%7C%20Streamable%20HTTP-7C3AED)](docs/configuration.md)\n[![Docker](https://img.shields.io/badge/Docker-ready-2496ED?logo=docker&logoColor=white)](docs/docker.md)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![MCP Toplist](https://mcptoplist.com/badge/io.github.swimmwatch%2Fcloakbrowser-mcp.svg)](https://mcptoplist.com/server/io.github.swimmwatch%2Fcloakbrowser-mcp)\n\n`cloakbrowser-mcp` is a drop-in Playwright MCP-compatible browser automation server with unchanged upstream tools, [CloakBrowser](https://github.com/CloakHQ/CloakBrowser) Chromium, and production-ready npm, Docker, and Streamable HTTP packaging. It runs upstream [`@playwright/mcp`](https://github.com/microsoft/playwright-mcp) as the canonical tool surface and points that runtime at CloakBrowser.\n\n## 30-second demo\n\n[![30-second demo showing CloakBrowser MCP startup, humanized research prompt typing, web automation, and testing workflows](docs/assets/videos/30-second-demo.webp)](docs/assets/videos/30-second-demo.mp4)\n\nRun `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.\n\nDocumentation: [swimmwatch.github.io/cloakbrowser-mcp](https://swimmwatch.github.io/cloakbrowser-mcp/) · [Comparison](https://swimmwatch.github.io/cloakbrowser-mcp/comparison/) · [Recipes](https://swimmwatch.github.io/cloakbrowser-mcp/recipes/)\n\nUse it when you need:\n\n- Playwright MCP browser automation backed by CloakBrowser;\n- unchanged upstream browser tools plus two local introspection tools;\n- npm or Docker installation over stdio or Streamable HTTP;\n- persistent browser profiles, validated context options, and Chrome extension loading;\n- GeoIP-aware proxy matching for regional QA;\n- humanized mouse, keyboard, and scroll behavior for interaction-sensitive flows.\n\nCross-platform checks cover npm on Linux x64/arm64, macOS arm64/x64, and Windows x64 across Node.js 22 and 24-26. Docker images are built and smoke-tested for `linux/amd64` and `linux/arm64`.\n\nSee [`@playwright/mcp` vs `cloakbrowser-mcp`](docs/comparison.md) when deciding whether plain upstream Playwright MCP or CloakBrowser MCP fits a deployment better. The [Recipes](docs/recipes/index.md) pages show task-focused setup paths for persistent login profiles, Chrome extensions, reverse proxies, regional QA, client connections, and CI smoke tests.\n\n## Install With npm\n\n```bash\nnpx -y cloakbrowser-mcp@latest\n```\n\nRequires Node.js 22.13+ in the 22.x line, or Node.js 24+. Run diagnostics before wiring a client:\n\n```bash\nnpx -y cloakbrowser-mcp@latest doctor\n```\n\nFor Streamable HTTP instead of stdio:\n\n```bash\nnpx -y cloakbrowser-mcp@latest --transport streamable-http --http-port 3000\n```\n\nSee the generated [CLI Reference](https://swimmwatch.github.io/cloakbrowser-mcp/generated/cli/) for all flags.\n\n## Install With Docker\n\n```bash\ndocker run --rm --init -i \\\n -v \"$PWD/artifacts:/data\" \\\n swimmwatch/cloakbrowser-mcp:latest\n```\n\nFor Streamable HTTP:\n\n```bash\ndocker run --rm --init -p 127.0.0.1:3000:3000 \\\n -v \"$PWD/artifacts:/data\" \\\n swimmwatch/cloakbrowser-mcp:latest \\\n --transport streamable-http --http-host 0.0.0.0 --http-port 3000\n```\n\nThe 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](docs/docker.md) for persistent profiles, extension mounts, HTTPS, and smoke-test examples, or use the [reverse proxy recipe](docs/recipes/docker-streamable-http-reverse-proxy.md) for a focused Streamable HTTP deployment.\n\n## Add To MCP Clients\n\n### Codex CLI\n\n```bash\ncodex mcp add cloakbrowser -- npx -y cloakbrowser-mcp@latest\n```\n\n### Claude Code\n\n```bash\nclaude mcp add --transport stdio cloakbrowser -- npx -y cloakbrowser-mcp@latest\n```\n\n### GitHub Copilot In VS Code\n\n```json\n{\n \"servers\": {\n \"cloakbrowser\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"cloakbrowser-mcp@latest\"]\n }\n }\n}\n```\n\n### Claude Desktop, Cursor, Cline, Windsurf, Warp, And Other `mcpServers` Clients\n\nAdd this server entry to the client's MCP JSON config:\n\n```json\n{\n \"mcpServers\": {\n \"cloakbrowser\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"cloakbrowser-mcp@latest\"]\n }\n }\n}\n```\n\n### Docker-backed stdio\n\n```json\n{\n \"mcpServers\": {\n \"cloakbrowser\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"--init\",\n \"-i\",\n \"-v\",\n \"/tmp/cloakbrowser-artifacts:/data\",\n \"swimmwatch/cloakbrowser-mcp:latest\"\n ]\n }\n }\n}\n```\n\n### Already-running Streamable HTTP server\n\n```bash\nnpx -y cloakbrowser-mcp@latest --transport streamable-http --http-port 3000\ncodex mcp add cloakbrowser --url http://127.0.0.1:3000/mcp\nclaude mcp add --transport http cloakbrowser http://127.0.0.1:3000/mcp\n```\n\n### Prompt For A Code Assistant\n\nPaste this into Codex, Claude Code, Copilot, Cursor, Cline, Windsurf, or a similar coding assistant that can edit MCP config:\n\n```text\nInstall the CloakBrowser MCP server for this workspace. Name it \"cloakbrowser\".\nPrefer stdio with command \"npx\" and args [\"-y\", \"cloakbrowser-mcp@latest\"].\nIf this client uses VS Code mcp.json, add it under \"servers\" with type \"stdio\".\nIf this client uses Claude/Cursor/Cline/Windsurf/Warp-style config, add it under\n\"mcpServers\" with the same command and args. Do not add secrets.\n```\n\nMore examples are in [Getting Started](docs/getting-started.md), with dedicated recipes for [Claude Desktop](docs/recipes/connect-claude-desktop.md) and [Codex CLI](docs/recipes/connect-codex-cli.md).\n\n## Configuration\n\nUse 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`.\n\nThe common variable table now lives in [Configuration](docs/configuration.md). That page also covers persistent profiles, validated context options, Chrome extensions, Streamable HTTP metadata, and HTTPS/auth options. See [GeoIP Proxy Matching](docs/geoip-proxy-matching.md) for regional proxy behavior, [Humanized Input Behavior](docs/humanized-input-behavior.md) for interaction realism, and [Recipes](docs/recipes/index.md) for task-focused configurations.\n\n## Version Compatibility\n\n\n\n| cloakbrowser-mcp | @playwright/mcp | CloakBrowser | Node.js | Platform |\n| ---------------- | --------------- | ------------ | ---------------------- | ----------------------------------------------------------------------------------------- |\n| `1.13.0` | `^0.0.80` | `^0.5.10` | `^22.13.0 || >=24.0.0` | npm on Linux x64/arm64, macOS arm64/x64, Windows x64; Docker `linux/amd64`, `linux/arm64` |\n| `1.12.0` | `^0.0.79` | `^0.5.7` | `^22.13.0 || >=24.0.0` | npm on Linux x64/arm64, macOS arm64/x64, Windows x64; Docker `linux/amd64`, `linux/arm64` |\n| `1.11.0` | `^0.0.79` | `^0.5.6` | `^22.13.0 || >=24.0.0` | npm on Linux x64/arm64, macOS arm64/x64, Windows x64; Docker `linux/amd64`, `linux/arm64` |\n| `1.10.0` | `^0.0.78` | `^0.5.3` | `^22.13.0 || >=24.0.0` | npm on Linux x64/arm64, macOS arm64/x64, Windows x64; Docker `linux/amd64`, `linux/arm64` |\n| `1.9.0` | `^0.0.78` | `^0.5.1` | `^22.13.0 || >=24.0.0` | npm on Linux x64/arm64, macOS arm64/x64, Windows x64; Docker `linux/amd64`, `linux/arm64` |\n| `1.8.0` | `^0.0.78` | `^0.4.10` | `^22.13.0 || >=24.0.0` | npm on Linux x64/arm64, macOS arm64/x64, Windows x64; Docker `linux/amd64`, `linux/arm64` |\n| `1.7.0` | `^0.0.77` | `^0.4.8` | `>=22.12` | npm on Linux x64/arm64, macOS arm64/x64, Windows x64; Docker `linux/amd64`, `linux/arm64` |\n| `1.6.1` | `^0.0.77` | `^0.4.7` | `>=22.12` | npm on Linux x64/arm64, macOS arm64/x64, Windows x64; Docker `linux/amd64`, `linux/arm64` |\n| `1.6.0` | `^0.0.77` | `^0.4.7` | `>=22.12` | npm on Linux x64/arm64, macOS arm64/x64, Windows x64; Docker `linux/amd64`, `linux/arm64` |\n| `1.5.0` | `^0.0.76` | `^0.4.3` | `>=22.12` | npm on Linux x64/arm64, macOS arm64/x64, Windows x64; Docker `linux/amd64`, `linux/arm64` |\n| `1.4.0` | `^0.0.76` | `^0.3.32` | `>=22.12` | npm on Linux x64/arm64, macOS arm64/x64, Windows x64; Docker `linux/amd64`, `linux/arm64` |\n| `1.3.0` | `^0.0.75` | `^0.3.31` | `>=20` | Docker `linux/amd64`, Node.js local |\n| `1.2.7` | `^0.0.75` | `^0.3.30` | `>=20` | Docker `linux/amd64`, Node.js local |\n| `1.2.6` | `^0.0.75` | `^0.3.30` | `>=20` | Docker `linux/amd64`, Node.js local |\n| `1.2.5` | `^0.0.75` | `^0.3.30` | `>=20` | Docker `linux/amd64`, Node.js local |\n| `1.2.3` | `^0.0.75` | `^0.3.30` | `>=20` | Docker `linux/amd64`, Node.js local |\n| `1.2.2` | `^0.0.75` | `^0.3.30` | `>=20` | Docker `linux/amd64`, Node.js local |\n| `1.2.1` | `^0.0.75` | `^0.3.30` | `>=20` | Docker `linux/amd64`, Node.js local |\n| `1.2.0` | `^0.0.75` | `^0.3.30` | `>=20` | Docker `linux/amd64`, Node.js local |\n| `1.1.0` | `^0.0.75` | `^0.3.30` | `>=20` | Docker `linux/amd64`, Node.js local |\n| `1.0.2` | `^0.0.75` | `^0.3.30` | `>=20` | Docker `linux/amd64`, Node.js local |\n| `1.0.1` | `^0.0.75` | `^0.3.30` | `>=20` | Docker `linux/amd64`, Node.js local |\n| `1.0.0` | `^0.0.75` | `^0.3.30` | `>=20` | Docker `linux/amd64`, Node.js local |\n\n\n\nSee [Version Compatibility](docs/version-compatibility.md) for the maintained compatibility table.\n\n## Tools\n\nThe upstream Playwright MCP tool list is authoritative. This project does not reimplement or re-document upstream browser schemas in source code.\n\nLocal tools:\n\n- `cloakbrowser_binary_info` returns CloakBrowser package, platform, cache, and resolved binary data.\n- `cloakbrowser_bridge_info` returns bridge metadata, upstream package/version, and local tool names.\n\n## Development\n\n```bash\nnpm install\nnpm run build\nnpm test\nnpm run docker:build\nnpm run docker:smoke\nnpm run server:validate\nnpm run bridge:compare -- cloakbrowser-mcp:dev --report bridge-parity-report.json\n```\n\nDocumentation starts at [docs/getting-started.md](docs/getting-started.md). Contributor material is grouped under [docs/contributor-guide.md](docs/contributor-guide.md).\n", "bytes": 15647, "sha": "1d1deb5f04354f6d52b0d99054964d1808f073b4ce2ea4543ed9d381f5ea5668", "repo_slug": "swimmwatch/cloakbrowser-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_swimmwatch_cloakbrowser_mcp_66003490/readme" }