Docker¶

The published image is the recommended runtime for repeatable MCP usage.

Run¶

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

Artifacts are written to /data in the container. Mount that path to keep screenshots, snapshots, downloads, and network output.

--init is recommended because browser automation can create short-lived child processes. Docker's init process reaps those children cleanly.

Streamable HTTP¶

For local Streamable HTTP usage, publish the container port on loopback:

docker run --rm --init -p 127.0.0.1:3000:3000 \
  -v "$PWD/artifacts:/data" \
  ghcr.io/swimmwatch/cloakbrowser-mcp:latest \
  --transport streamable-http --http-host 0.0.0.0 --http-port 3000

The host-side 127.0.0.1:3000 bind keeps the endpoint local. If you publish Streamable HTTP on a non-loopback interface, put it behind authentication, TLS, and network controls. See the generated CLI Reference for all HTTP transport flags and environment variables.

Defaults¶

MCP Client Config¶

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

Build Locally¶

npm run docker:build
npm run docker:smoke

The Dockerfile uses the pinned official Playwright MCP image as the runtime base, applies available Debian security updates during the build, removes the unused global npm payload from the runtime image, and installs the bridge under /opt/cloakbrowser-mcp.

The release workflow publishes SBOM and provenance attestations, includes OCI labels for source, revision, version, license, base image name, and base image digest, and scans the built image with Trivy before publishing.