cloakbrowser-mcp-server

Headed wrapper around swimmwatch/cloakbrowser-mcp that exposes the Chromium browser over VNC so a human can watch the same session an MCP client is driving over Streamable HTTP.

The whole project is one Python launcher + one Dockerfile. It starts Xvfb + openbox so Chromium runs headed (required by anti-bot probes that inspect window/widget state), mirrors the display with x11vnc, then execs the upstream cloakbrowser-mcp CLI in Streamable HTTP mode.

Quick start

docker build -t cloakbrowser-mcp-server .

docker run --rm \
  -p 3000:3000 \
  -e VNC_PASSWORD=changeme \
  cloakbrowser-mcp-server

Then:

1. MCP client — point it at http://localhost:3000/mcp (any Streamable HTTP MCP client: Claude Desktop via claude mcp add --transport http cloakbrowser http://localhost:3000/mcp, Codex CLI, Cursor, etc.)

2. VNC viewer — connect to localhost:5900, password changeme. macOS built-in: open vnc://localhost:5900. Any VNC client works.

Related MCP server: agent-browser-mcp

Architecture

                    ┌────────────────────────────────────────────┐
                    │  container                                 │
   host ── 3000 ──► │  cloakbrowser-mcp (Streamable HTTP)        │
                    │   └─ Playwright MCP ──► Chromium headed    │
   host ── 5900 ──► │   Xvfb :99 + openbox  ◄── x11vnc mirror    │
                    │                                            │
                    │  /data (bind-mounted, persistent profile)  │
                    └────────────────────────────────────────────┘

scripts/launcher.py orchestrates the whole thing in one process:

1. SIGKILL any leftover Chromium from an earlier unclean container death — otherwise it keeps holding the SingletonLock on /data and the next run starts with the upstream User data directory is already active in this process error. Then remove any stale SingletonLock/SingletonSocket/SingletonCookie files just in case.

2. Xvfb :99 at 1920x1080x24

3. openbox (window manager so Chromium honours --start-maximized)

4. x11vnc on :5900, password from $VNC_PASSWORD or open

5. exec node /opt/cloakbrowser-mcp/dist/cli.js --transport streamable-http --http-host 0.0.0.0 --http-port 3000

6. force PLAYWRIGHT_MCP_HEADLESS=false in the child env (the wrapper's whole reason to exist)

7. wait for SIGTERM/SIGINT, tear down X + VNC

Configuration

Environment variables (wrapper-specific)

Any PLAYWRIGHT_MCP_* and CLOAK_PLAYWRIGHT_MCP_* variable is forwarded to the upstream cloakbrowser-mcp CLI untouched. See Configuration in the upstream docs for the full list. The wrapper only overrides:

• PLAYWRIGHT_MCP_HEADLESS=false (always)

• --transport streamable-http --http-host 0.0.0.0 --http-port 3000 (always)

MCP auth, persistent profiles, Chrome extensions, regional proxies, humanized input — all configured via upstream env vars.

Hardcoded (cannot be changed via env)

Volume

Bind-mount /data to persist Chromium's profile across container runs:

docker run --rm \
  -p 3000:3000 -p 5900:5900 \
  -v ~/cloak-mcp-data:/data \
  -e VNC_PASSWORD=changeme \
  cloakbrowser-mcp-server

Without the mount, /data lives inside the container and is lost on docker rm.

Port mapping

The internal MCP port is always 3000 and the internal VNC port is always 5900, regardless of what you map them to on the host:

# default: same ports on host and container
-p 3000:3000 -p 5900:5900

# remap both
-p 8080:3000 -p 5999:5900

Project layout

cloakbrowser-mcp-server/
├── Dockerfile             # FROM swimmwatch/cloakbrowser-mcp:latest + X stack
├── README.md
├── pyproject.toml         # ruff config (lint + format)
├── scripts/
│   └── launcher.py        # single-file orchestrator
└── tests/
    └── test_launcher.py   # stdlib unittest, no test framework dependency

No build system, no CI — keep it boring.

Lint & test

ruff check .                 # lint
ruff format --check .        # format check
ruff format .                # format fix
python3 -m unittest discover -s tests -v   # 12 unit tests, stdlib only
docker build -t cloakbrowser-mcp-server . # full image build (~30s with cached base)

License

Inherits MIT from cloakbrowser-mcp.