# CloakBrowser MCP

> CloakBrowser MCP is a stdio and Streamable HTTP Model Context Protocol server that runs upstream Playwright MCP browser tools with the CloakBrowser Chromium binary. It keeps upstream tool contracts unchanged while adding bridge configuration for persistent profiles, validated context options, Chrome extension paths, GeoIP-aware proxy matching, and humanized input behavior.

Documentation: https://swimmwatch.github.io/cloakbrowser-mcp/
Repository: https://github.com/swimmwatch/cloakbrowser-mcp
npm package: https://www.npmjs.com/package/cloakbrowser-mcp
Docker Hub image: https://hub.docker.com/r/swimmwatch/cloakbrowser-mcp
GHCR image: https://github.com/swimmwatch/cloakbrowser-mcp/pkgs/container/cloakbrowser-mcp

## Current Compatibility

- cloakbrowser-mcp: 1.13.0
- @playwright/mcp: ^0.0.80
- Playwright MCP Docker base: mcr.microsoft.com/playwright/mcp:v0.0.80
- CloakBrowser: ^0.5.10
- Transports: stdio and Streamable HTTP

## Key Pages

- Getting Started: https://swimmwatch.github.io/cloakbrowser-mcp/getting-started/
- Docker: https://swimmwatch.github.io/cloakbrowser-mcp/docker/
- Version Compatibility: https://swimmwatch.github.io/cloakbrowser-mcp/version-compatibility/
- Configuration: https://swimmwatch.github.io/cloakbrowser-mcp/configuration/
- GeoIP Proxy Matching: https://swimmwatch.github.io/cloakbrowser-mcp/geoip-proxy-matching/
- Humanized Input Behavior: https://swimmwatch.github.io/cloakbrowser-mcp/humanized-input-behavior/
- CLI Reference: https://swimmwatch.github.io/cloakbrowser-mcp/generated/cli/
- Tools: https://swimmwatch.github.io/cloakbrowser-mcp/tools/
- Security: https://swimmwatch.github.io/cloakbrowser-mcp/security/
- FAQ: https://swimmwatch.github.io/cloakbrowser-mcp/faq/

## Install

The recommended local stdio command for most MCP clients is:

```bash
npx -y cloakbrowser-mcp@latest
```

Docker stdio alternative:

```bash
docker run --rm --init -i -v /tmp/cloakbrowser-artifacts:/data swimmwatch/cloakbrowser-mcp:latest
```

Generic stdio JSON for Claude Desktop, Cursor, Cline-style clients, Windsurf, Warp, and other `mcpServers` clients:

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

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
```

VS Code `mcp.json`:

```json
{
  "servers": {
    "cloakbrowser": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "cloakbrowser-mcp@latest"]
    }
  }
}
```

Continue `.continue/mcpServers/cloakbrowser-mcp.yaml`:

```yaml
name: CloakBrowser MCP
version: 0.0.1
schema: v1
mcpServers:
  - name: CloakBrowser
    type: stdio
    command: npx
    args:
      - -y
      - cloakbrowser-mcp@latest
```

Streamable HTTP:

```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
```

Streamable HTTPS with direct TLS:

```bash
npx -y cloakbrowser-mcp@latest --transport streamable-http --http-protocol https --https-cert ./cert.pem --https-key ./key.pem
```

Stdio mode does not emit routine operational logs to stdout, so MCP JSON-RPC remains protocol-clean. Streamable HTTP mode writes startup and request logs to stdout. For non-loopback exposure, use HTTPS plus auth or TLS/auth at a trusted reverse proxy. See Getting Started and Configuration for complete options.

## Persistent Profiles, Context Options, And Extensions

Persistent Chromium profiles are opt-in. Set `PLAYWRIGHT_MCP_USER_DATA_DIR` for stdio or pass `userDataDir` in Streamable HTTP initialize metadata. The bridge resolves the directory to an absolute platform-native path, creates it if missing, verifies it is writable, writes it to generated `browser.userDataDir`, and avoids isolated mode when a persistent profile is configured.

Context options are validated before they reach generated Playwright MCP config. Set `CLOAK_PLAYWRIGHT_MCP_CONTEXT_OPTIONS` to a JSON object or pass `contextOptions` in Streamable HTTP initialize metadata. Supported fields are `userAgent`, `viewport`, `locale`, `timezoneId`, `colorScheme`, `permissions`, `geolocation`, `extraHTTPHeaders`, `httpCredentials`, `ignoreHTTPSErrors`, `offline`, `deviceScaleFactor`, `isMobile`, and `hasTouch`.

Chrome extension paths are opt-in through `CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS` or Streamable HTTP `extensionPaths`. Paths must point to existing directories and require a persistent `userDataDir`. The bridge resolves extension paths to absolute platform-native paths and asks CloakBrowser to generate the `--load-extension` and `--disable-extensions-except` launch arguments.

In Docker, use the existing `/data` volume as the persistence root. Set `PLAYWRIGHT_MCP_USER_DATA_DIR=/data/profiles/default` and mount artifacts with `-v "$PWD/artifacts:/data"`. Extension directories should be mounted separately, for example `-v "$PWD/extensions/my-extension:/extensions/my-extension:ro"` with `CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS=/extensions/my-extension`. Docker environment variables should use container paths, not host paths.

## GeoIP Proxy Matching

Set `PLAYWRIGHT_MCP_PROXY_SERVER` and `CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true` to align CloakBrowser timezone, language, and locale fingerprint flags with the proxy location while leaving proxy routing delegated to upstream Playwright MCP.

Streamable HTTP clients can override selected settings per MCP session with `initialize.params._meta["io.github.swimmwatch/cloakbrowser-mcp"]`. Supported fields include `proxyServer`, `proxyBypass`, `geoipProxyMatch`, `headless`, `humanize`, `humanPreset`, `userDataDir`, `contextOptions`, and `extensionPaths`. Session metadata overrides environment values. `contextOptions` are shallow-merged with environment options first and session options second. Existing HTTP sessions keep their initialization settings; create a new session to switch regions, headed/headless mode, persistent profile, context options, extensions, or humanized behavior.

Use GeoIP proxy matching for localization QA, regional landing page checks, commerce flows, support reproduction, and timezone-sensitive automation. It does not provide a proxy service, does not configure browser geolocation coordinates, and should not be treated as a bypass for access controls or regional policy checks.

## Humanized Input Behavior

Set `CLOAK_PLAYWRIGHT_MCP_HUMANIZE=true` or pass `humanize` in Streamable HTTP initialize metadata to enable CloakBrowser's human-like mouse, keyboard, and scroll behavior for page interactions. Set `CLOAK_PLAYWRIGHT_MCP_HUMAN_PRESET=default|careful` or runtime `humanPreset` to select the preset; `humanPreset` does not enable humanized behavior by itself.

Use humanized input behavior for form QA, checkout flows, interaction-sensitive UI tests, scroll-heavy pages, and demos where realistic pacing matters. It does not change upstream Playwright MCP tool schemas and is available only when the bridge runs with the CloakBrowser engine. Custom `humanConfig` objects are not supported yet because they need explicit schema validation.

## Runtime Headless Mode

Set `PLAYWRIGHT_MCP_HEADLESS` globally or pass `headless` in Streamable HTTP initialize metadata to choose headed or headless browser mode per session. Use `headless: false` only where a usable display environment is available, such as a local desktop session, Xvfb, or an equivalent container display setup.

## Tool Surface

Upstream Playwright MCP browser tools are forwarded unchanged. CloakBrowser MCP adds only two local introspection tools:

- cloakbrowser_binary_info
- cloakbrowser_bridge_info

## Diagnostics

- CLI diagnostics: `cloakbrowser-mcp doctor` or `cloakbrowser-mcp doctor --json`
- Streamable HTTP probes: `GET /healthz` and `GET /readyz`
- Probe authorization: when `--http-auth-token` is configured, probes require the same Bearer token as MCP requests.
