io.github.swimmwatch/cloakbrowser-mcp

Official

by swimmwatch · TypeScript

CloakBrowser MCP

Playwright MCP-compatible browser automation bridge for CloakBrowser Chromium.

Browser automation using Playwright with CloakBrowser Chromium.

playwrightbrowser automationchromiumweb scrapingcloakbrowserautomation

Topics

ai-agentsai-toolsbrowser-automationchromiumcloakbrowserdockerheadless-browserllm-toolsmcpmcp-servermcp-toolsmodel-context-protocolmodelcontextprotocolplaywrightplaywright-mcptypescriptweb-automation

README.md12 KBView on GitHub

cloakbrowser-mcp

cloakbrowser-mcp is a Model Context Protocol browser automation server that runs upstream @playwright/mcp with the CloakBrowser Chromium binary. It gives MCP clients Playwright-compatible browser tools while keeping the upstream tool contracts unchanged.

Documentation: swimmwatch.github.io/cloakbrowser-mcp

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;
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 Node.js 22-26. Docker images are built and smoke-tested for linux/amd64 and linux/arm64.

Install With npm

bash

npx -y cloakbrowser-mcp@latest

Requires Node.js 22.12 or newer. Run diagnostics before wiring a client:

bash

npx -y cloakbrowser-mcp@latest doctor

For Streamable HTTP instead of stdio:

bash

npx -y cloakbrowser-mcp@latest --transport streamable-http --http-port 3000

See the generated CLI Reference for all flags.

Install With Docker

bash

docker run --rm --init -i \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest

For Streamable HTTP:

bash

docker run --rm --init -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. The same tags are also available from ghcr.io/swimmwatch/cloakbrowser-mcp. See Docker for persistent profiles, extension mounts, HTTPS, and smoke-test examples.

Add To MCP Clients

Codex CLI

bash

codex mcp add cloakbrowser -- npx -y cloakbrowser-mcp@latest

Claude Code

bash

claude mcp add --transport stdio cloakbrowser -- npx -y cloakbrowser-mcp@latest

GitHub Copilot In VS Code

json

{
  "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:

json

{
  "mcpServers": {
    "cloakbrowser": {
      "command": "npx",
      "args": ["-y", "cloakbrowser-mcp@latest"]
    }
  }
}

Docker-backed stdio

json

{
  "mcpServers": {
    "cloakbrowser": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "--init",
        "-i",
        "-v",
        "/tmp/cloakbrowser-artifacts:/data",
        "swimmwatch/cloakbrowser-mcp:latest"
      ]
    }
  }
}

Already-running Streamable HTTP server

bash

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:

text

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.

Configuration

Use upstream PLAYWRIGHT_MCP_* variables for browser, artifacts, timeouts, network, and tool capability settings. Cloak-specific bridge toggles use CLOAK_PLAYWRIGHT_MCP_*.

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 and Humanized Input Behavior for interaction realism.

Version Compatibility

cloakbrowser-mcp	@playwright/mcp	CloakBrowser	Node.js	Platform
`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`
`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`
`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`
`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`
`1.3.0`	`^0.0.75`	`^0.3.31`	`>=20`	Docker `linux/amd64`, Node.js local
`1.2.7`	`^0.0.75`	`^0.3.30`	`>=20`	Docker `linux/amd64`, Node.js local
`1.2.6`	`^0.0.75`	`^0.3.30`	`>=20`	Docker `linux/amd64`, Node.js local
`1.2.5`	`^0.0.75`	`^0.3.30`	`>=20`	Docker `linux/amd64`, Node.js local
`1.2.3`	`^0.0.75`	`^0.3.30`	`>=20`	Docker `linux/amd64`, Node.js local
`1.2.2`	`^0.0.75`	`^0.3.30`	`>=20`	Docker `linux/amd64`, Node.js local
`1.2.1`	`^0.0.75`	`^0.3.30`	`>=20`	Docker `linux/amd64`, Node.js local
`1.2.0`	`^0.0.75`	`^0.3.30`	`>=20`	Docker `linux/amd64`, Node.js local
`1.1.0`	`^0.0.75`	`^0.3.30`	`>=20`	Docker `linux/amd64`, Node.js local
`1.0.2`	`^0.0.75`	`^0.3.30`	`>=20`	Docker `linux/amd64`, Node.js local
`1.0.1`	`^0.0.75`	`^0.3.30`	`>=20`	Docker `linux/amd64`, Node.js local
`1.0.0`	`^0.0.75`	`^0.3.30`	`>=20`	Docker `linux/amd64`, Node.js local

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_info returns CloakBrowser package, platform, cache, and resolved binary data.
cloakbrowser_bridge_info returns bridge metadata, upstream package/version, and local tool names.

Development

bash

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.

Install

Configuration

Environment variables

PLAYWRIGHT_MCP_BROWSER_ENGINEdefault cloak

Bridge browser engine: cloak or playwright.

PLAYWRIGHT_MCP_HEADLESSdefault true

Run the browser in headless mode.

PLAYWRIGHT_MCP_OUTPUT_DIRdefault .playwright-mcp

Directory where upstream Playwright MCP writes artifacts.

PLAYWRIGHT_MCP_OUTPUT_MODEdefault stdout

Return snapshots, console logs, and network logs through stdout or files.

PLAYWRIGHT_MCP_USER_DATA_DIR

Persistent Chromium profile directory. The bridge resolves it to an absolute path and writes it to generated Playwright MCP config.

CLOAK_PLAYWRIGHT_MCP_CONTEXT_OPTIONS

JSON object with validated Playwright context options such as viewport, locale, timezoneId, permissions, geolocation, and headers.

CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS

JSON array or comma-separated list of Chrome extension directories. Requires PLAYWRIGHT_MCP_USER_DATA_DIR.

CLOAK_PLAYWRIGHT_MCP_CONSOLE_FALLBACKdefault true

Patch upstream console message collection for CloakBrowser compatibility.

CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCHdefault false

Resolve proxy GeoIP and match CloakBrowser timezone/locale fingerprint flags when PLAYWRIGHT_MCP_PROXY_SERVER is set.

CLOAK_PLAYWRIGHT_MCP_EXTRA_ARGS

Comma-separated or JSON array of extra Chromium launch arguments.

CLOAK_PLAYWRIGHT_MCP_HTTP_HOSTdefault 127.0.0.1

Streamable HTTP bind host.

CLOAK_PLAYWRIGHT_MCP_HTTP_PORTdefault 3000

Streamable HTTP bind port.

CLOAK_PLAYWRIGHT_MCP_HTTP_ENDPOINTdefault /mcp

Streamable HTTP endpoint path.

CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKENsecret

Optional Streamable HTTP Bearer token.

CLOAK_PLAYWRIGHT_MCP_HTTP_SESSION_BACKENDdefault memory

Session metadata backend. Only memory is implemented in this release.

CLOAK_PLAYWRIGHT_MCP_HTTP_SESSION_IDLE_TTL_MSdefault 3600000

Idle TTL for Streamable HTTP sessions.

CLOAK_PLAYWRIGHT_MCP_HTTP_SESSION_MAXdefault 32

Maximum active Streamable HTTP sessions in one process.

Arguments

--transportdefault streamable-http

claude_desktop_config.json

{
  "mcpServers": {
    "cloakbrowser-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "cloakbrowser-mcp@1.6.1"
      ],
      "env": {
        "PLAYWRIGHT_MCP_BROWSER_ENGINE": "cloak",
        "PLAYWRIGHT_MCP_HEADLESS": "true",
        "PLAYWRIGHT_MCP_OUTPUT_DIR": ".playwright-mcp",
        "PLAYWRIGHT_MCP_OUTPUT_MODE": "stdout",
        "PLAYWRIGHT_MCP_USER_DATA_DIR": "<YOUR_PLAYWRIGHT_MCP_USER_DATA_DIR>",
        "CLOAK_PLAYWRIGHT_MCP_CONTEXT_OPTIONS": "<YOUR_CLOAK_PLAYWRIGHT_MCP_CONTEXT_OPTIONS>",
        "CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS": "<YOUR_CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS>",
        "CLOAK_PLAYWRIGHT_MCP_CONSOLE_FALLBACK": "true",
        "CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH": "false",
        "CLOAK_PLAYWRIGHT_MCP_EXTRA_ARGS": "<YOUR_CLOAK_PLAYWRIGHT_MCP_EXTRA_ARGS>"
      }
    }
  }
}

Topics

cloakbrowser-mcp

Install With npm

Install With Docker

Add To MCP Clients

Codex CLI

Claude Code

GitHub Copilot In VS Code

Claude Desktop, Cursor, Cline, Windsurf, Warp, And Other mcpServers Clients

Docker-backed stdio

Already-running Streamable HTTP server

Prompt For A Code Assistant

Configuration

Version Compatibility

Tools

Development

Install

Configuration

Claude Desktop, Cursor, Cline, Windsurf, Warp, And Other `mcpServers` Clients