DEV Community

Cover image for CloakBrowser MCP: Playwright MCP tools with a CloakBrowser Chromium runtime
Dmitry Vasiliev
Dmitry Vasiliev

Posted on

CloakBrowser MCP: Playwright MCP tools with a CloakBrowser Chromium runtime

#ai #mcp #playwright #opensource

Browser automation is becoming one of the most useful tool categories for AI agents.

If an agent can open a page, inspect the accessibility tree, click buttons, fill forms, read console output, and take screenshots, it can help with tasks that are hard to solve through APIs alone: debugging frontend flows, checking documentation, testing onboarding, validating generated UI, and reproducing browser-only bugs.

Playwright MCP is already a strong foundation for that workflow. It gives MCP clients a browser automation surface built around Playwright. The question that led to CloakBrowser MCP was narrower:

What if you want the same upstream Playwright MCP tools, but with a different Chromium runtime?

That is what cloakbrowser-mcp does.

What is CloakBrowser MCP?

cloakbrowser-mcp is an open-source Model Context Protocol server that runs upstream @playwright/mcp with the CloakBrowser Chromium executable.

The project is intentionally thin:

  • upstream Playwright MCP owns the browser tool schemas, descriptions, and responses
  • cloakbrowser-mcp generates a Playwright MCP config that points launchOptions.executablePath to CloakBrowser
  • upstream browser tools are forwarded unchanged
  • the bridge adds only two local diagnostic tools

Those local tools are:

  • cloakbrowser_binary_info
  • cloakbrowser_bridge_info

Everything else comes from upstream Playwright MCP.

Repository:

https://github.com/swimmwatch/cloakbrowser-mcp

Docs:

https://swimmwatch.github.io/cloakbrowser-mcp/

npm:

https://www.npmjs.com/package/cloakbrowser-mcp

What it is not

This is not a custom browser automation API.

It is not a fork that rewrites Playwright MCP tool contracts.

It is not a CAPTCHA-solving service, and it should not be treated as a replacement for proper test-environment controls, allowlists, or site-owner-approved automation paths.

The goal is narrower and more maintainable: keep the Playwright MCP surface familiar, while letting users run that surface with CloakBrowser Chromium in local or Docker-backed agent workflows.

Why preserve the upstream Playwright MCP contract?

Browser MCP servers can become painful when every server invents a slightly different tool surface.

If the tool names, schemas, and behavior drift, users have to relearn the same browser workflow for each runtime. Clients and prompts also become less portable.

cloakbrowser-mcp takes the opposite approach. The bridge stays small and lets upstream Playwright MCP remain authoritative for browser tools.

That matters for a few reasons:

  1. Existing Playwright MCP workflows stay familiar.
  2. Upstream improvements can be adopted without redesigning a parallel tool model.
  3. The bridge can focus on runtime wiring, diagnostics, packaging, and parity checks.
  4. Users can compare behavior against upstream Playwright MCP more easily.

The project also runs parity checks against upstream default tools in CI, so changes to the forwarded tool surface are visible during development.

Quick start with npm

Requires Node.js 20 or newer.

npx -y cloakbrowser-mcp@latest --help
npx -y cloakbrowser-mcp@latest doctor
npx -y cloakbrowser-mcp@latest
Enter fullscreen mode Exit fullscreen mode

Use doctor first if you want a local diagnostic check before wiring the server into an MCP client:

npx -y cloakbrowser-mcp@latest doctor --json
Enter fullscreen mode Exit fullscreen mode

The default transport is stdio, which is what most local MCP client configs expect.

For Streamable HTTP:

npx -y cloakbrowser-mcp@latest \
  --transport streamable-http \
  --http-port 3000
Enter fullscreen mode Exit fullscreen mode

That exposes MCP at:

http://127.0.0.1:3000/mcp
Enter fullscreen mode Exit fullscreen mode

It also provides health probes:

curl http://127.0.0.1:3000/healthz
curl http://127.0.0.1:3000/readyz
Enter fullscreen mode Exit fullscreen mode

MCP client config

Most MCP clients use the same stdio shape: command, args, and optional env.

{
  "mcpServers": {
    "cloakbrowser": {
      "command": "npx",
      "args": ["-y", "cloakbrowser-mcp@latest"],
      "env": {
        "PLAYWRIGHT_MCP_HEADLESS": "true",
        "PLAYWRIGHT_MCP_OUTPUT_DIR": "/tmp/cloakbrowser-artifacts"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Use the same pattern in clients such as Claude Desktop, Cursor, VS Code, Cline, Continue, Windsurf, Goose, Warp, and Codex, adjusting only the surrounding config format if the client uses TOML or YAML instead of JSON.

Docker

Docker is useful when you want a repeatable runtime. The image is based on the pinned official Playwright MCP image and includes the bridge.

docker pull swimmwatch/cloakbrowser-mcp:latest
docker run --rm --init -i \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:latest
Enter fullscreen mode Exit fullscreen mode

For Streamable HTTP in Docker:

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
Enter fullscreen mode Exit fullscreen mode

The same images are also published to GitHub Container Registry:

ghcr.io/swimmwatch/cloakbrowser-mcp
Enter fullscreen mode Exit fullscreen mode

What tools should appear?

Ask your MCP client to list tools. You should see upstream Playwright MCP browser tools, such as:

  • browser_navigate
  • browser_click
  • browser_type
  • browser_snapshot
  • browser_take_screenshot
  • browser_console_messages
  • browser_network_requests
  • browser_evaluate
  • browser_tabs

You should also see the two local diagnostic tools:

  • cloakbrowser_binary_info
  • cloakbrowser_bridge_info

The diagnostic tools are there to answer practical setup questions:

  • Which bridge version is running?
  • Which upstream Playwright MCP package/version is resolved?
  • Which browser engine is configured?
  • Where is the CloakBrowser binary?
  • Which output directory is active?

Configuration

The primary configuration namespace is the upstream Playwright MCP namespace:

PLAYWRIGHT_MCP_*
Enter fullscreen mode Exit fullscreen mode

For Cloak-specific bridge toggles:

CLOAK_PLAYWRIGHT_MCP_*
Enter fullscreen mode Exit fullscreen mode

Common examples:

PLAYWRIGHT_MCP_HEADLESS=true
PLAYWRIGHT_MCP_OUTPUT_DIR=/tmp/cloakbrowser-artifacts
PLAYWRIGHT_MCP_OUTPUT_MODE=stdout
CLOAK_PLAYWRIGHT_MCP_CONSOLE_FALLBACK=true
CLOAK_PLAYWRIGHT_MCP_STEALTH_ARGS=true
Enter fullscreen mode Exit fullscreen mode

For local HTTP transport:

CLOAK_PLAYWRIGHT_MCP_TRANSPORT=streamable-http
CLOAK_PLAYWRIGHT_MCP_HTTP_HOST=127.0.0.1
CLOAK_PLAYWRIGHT_MCP_HTTP_PORT=3000
CLOAK_PLAYWRIGHT_MCP_HTTP_ENDPOINT=/mcp
Enter fullscreen mode Exit fullscreen mode

If you expose HTTP outside a local development machine, configure an auth token:

CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN=...
Enter fullscreen mode Exit fullscreen mode

Operational notes

A few details are worth knowing before using it in a real workflow:

  • The first browser action may download the CloakBrowser binary if it is not already cached.
  • Runtime logs must not go to stdout because MCP stdio uses stdout for protocol messages.
  • Docker runs should keep -i so stdio stays connected.
  • Docker runs should include --init so browser child processes are reaped correctly.
  • Artifacts should be written to a known output directory, especially in Docker.
  • For reproducibility, pin a version instead of using latest.

Example:

npx -y cloakbrowser-mcp@1.3.0
Enter fullscreen mode Exit fullscreen mode

Or:

docker run --rm --init -i \
  -v "$PWD/artifacts:/data" \
  swimmwatch/cloakbrowser-mcp:1.3.0
Enter fullscreen mode Exit fullscreen mode

When should you use it?

It is a good fit when you want:

  • Playwright MCP-compatible browser tools
  • a local stdio MCP server
  • a Docker-ready browser automation runtime
  • Streamable HTTP for clients that connect over HTTP
  • a CloakBrowser Chromium runtime without changing upstream Playwright MCP tool contracts
  • simple diagnostics before wiring the server into an agent

It is probably not the right fit if:

  • you need a hosted browser service
  • you want a custom high-level browser API instead of Playwright MCP tools
  • your workflow should use official APIs instead of browser automation
  • your testing environment can solve the problem with first-party test keys or allowlists

Try it

The fastest path is:

npx -y cloakbrowser-mcp@latest doctor
Enter fullscreen mode Exit fullscreen mode

Then add the stdio config to your MCP client:

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

Project links:

Feedback is welcome, especially from people already using Playwright MCP in local agent workflows.

Top comments (0)