Adding Playwright MCP + CloakBrowser to an Agent

Nite included in Tutorials

2026-05-19 About 600 words 3 minutes

Contents

Many Agents ship with built-in browser_* tools. They are fine for reading a page, but not great once you need to log in, fill out forms, or submit something. Playwright MCP is a Microsoft-maintained MCP server that exposes Playwright browser automation to an Agent.

Plain Playwright can run into trouble on modern anti-bot checks. navigator.webdriver = true, an empty plugin list, and a mismatched TLS fingerprint are common automation signals. The idea is to keep Playwright MCP as the Agent entry point, but switch the underlying browser to CloakBrowser, or, in a WSL setup, call the Windows host browser environment directly.

Shared part

The shared part only does one thing: install CloakBrowser and confirm the browser binary path. Hermes MCP config does not belong here, because Linux and Windows / WSL use different launch methods.

CloakBrowser can be installed as a Python package. With uv:

uv tool install cloakbrowser

# If uv tool commands need to be added to PATH
# uv tool update-shell

cloakbrowser install
cloakbrowser info

cloakbrowser install downloads the browser binary. cloakbrowser info shows the exact browser installation path.

Linux setup

In the Linux setup, the Agent, Playwright MCP, and CloakBrowser all run in the same Linux environment. There are two files: Playwright MCP’s own config.json, and the Agent’s MCP config.

Playwright MCP config file, for example:

/home/<username>/.hermes/playwright-mcp/config.json:

{
  "browser": {
    "browserName": "chromium",
    "launchOptions": {
      "executablePath": "/home/<username>/.cloakbrowser/chromium-{version}/chrome"
    }
  },
  "outputDir": "/tmp/playwright-mcp"
}

Replace executablePath with the real path shown by cloakbrowser info.

Hermes ~/.hermes/config.yaml:

mcp_servers:
  playwright-cloak:
    enabled: true
    command: npx
    args:
      - "@playwright/mcp@latest"
      - "--caps=storage"
      - "--config"
      - "/home/<username>/.hermes/playwright-mcp/config.json"
      - "--headless"

--caps=storage adds cookie and localStorage tools, for example:

Tool	Purpose
`browser_storage_state`	Save cookies + localStorage to a file
`browser_set_storage_state`	Restore from a file
`browser_cookie_list/get/set/delete/clear`	Manage individual cookies precisely

If login state needs to be loaded explicitly, use --storage-state:

mcp_servers:
  playwright-cloak:
    enabled: true
    command: npx
    args:
      - "@playwright/mcp@latest"
      - "--caps=storage"
      - "--config"
      - "/home/<username>/.hermes/playwright-mcp/config.json"
      - "--headless"
      - "--isolated"
      - "--storage-state=/home/<username>/.hermes/playwright-mcp/storage-state.json"

Verify it:

hermes mcp test playwright-cloak

A working setup prints something like this:

✓ Connected
✓ Tools discovered

Windows / WSL setup

This setup is for Hermes running inside WSL while Playwright MCP uses Windows-side Node.js and a Windows browser. It avoids WSL graphics, GPU, and Turnstile-related problems.

Put Playwright MCP’s config.json on the Windows side, for example:

C:\Users\<username>\.hermes\playwright-mcp\config.json:

{
  "browser": {
    "launchOptions": {
      "executablePath": "C:/Users/<username>/.cloakbrowser/chromium-{version}/chrome.exe"
    },
    "contextOptions": {
      "viewport": { "width": 1280, "height": 720 }
    }
  },
  "outputDir": "C:/Users/<username>/.hermes/playwright-mcp/output"
}

WSL-side ~/.hermes/config.yaml:

Do not set Hermes command directly to /mnt/c/Program Files/nodejs/npx. When a Windows program is started from WSL, child processes may receive a \\wsl.localhost\... UNC working directory. That makes the CMD / Node chain unstable.

A more reliable setup makes Hermes call powershell.exe, enter the Windows user directory first, and then start npx.cmd.

mcp_servers:
  playwright-cloak:
    enabled: true
    command: powershell.exe
    args:
      - -NoProfile
      - -ExecutionPolicy
      - Bypass
      - -Command
      - >-
        Set-Location $env:USERPROFILE;
        & "C:\Program Files\nodejs\npx.cmd"
        @playwright/mcp@latest
        --caps=storage
        --config "C:\Users\<username>\.hermes\playwright-mcp\config.json"
        --headless
    connect_timeout: 90.0

A few details:

Set-Location $env:USERPROFILE avoids the WSL UNC working directory.
connect_timeout can be slightly increased. The first npx startup or package download can be slow.

Verification command:

hermes mcp test playwright-cloak

A working setup looks like this:

Testing 'playwright-cloak'...
  Transport: stdio → powershell.exe
  Auth: none
  ✓ Connected
  ✓ Tools discovered

Proxy configuration

Modify Playwright’s config.json to set the proxy server:

{
  "browser": {
    "launchOptions": {
      "executablePath": "...",
      "proxy": {
        "server": "http://127.0.0.1:7900"
      }
    }
  },
  "outputDir": "..."
}

Adding Playwright MCP + CloakBrowser to an Agent

Shared part

Linux setup

Windows / WSL setup

Proxy configuration

Related links