# 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.

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

## Key Pages

- Getting Started: https://swimmwatch.github.io/cloakbrowser-mcp/getting-started/
- Docker: https://swimmwatch.github.io/cloakbrowser-mcp/docker/
- Configuration: https://swimmwatch.github.io/cloakbrowser-mcp/configuration/
- GeoIP Proxy Matching: https://swimmwatch.github.io/cloakbrowser-mcp/geoip-proxy-matching/
- 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.

## 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 proxy settings per MCP session with `initialize.params._meta["io.github.swimmwatch/cloakbrowser-mcp"]`. Supported fields are `proxyServer`, `proxyBypass`, and `geoipProxyMatch`. Existing HTTP sessions keep their initialization proxy settings; create a new session to switch regions.

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.

## 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.
