# Adding Playwright MCP + CloakBrowser to an Agent


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`:

```shell
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`:

```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`:

```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`:

```yaml
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:

```shell
hermes mcp test playwright-cloak
```

A working setup prints something like this:

```text
✓ 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`:

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

```yaml
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:

```shell
hermes mcp test playwright-cloak
```

A working setup looks like this:

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

## Proxy configuration

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

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

## Related links

- [Playwright MCP](https://github.com/microsoft/playwright-mcp)
- [CloakBrowser](https://github.com/CloakHQ/CloakBrowser)
- [Playwright MCP Storage Tools docs](https://playwright.dev/mcp/tools/storage)
- [Hermes Agent MCP configuration docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)


---

> Author: Nite  
> URL: https://www.nite07.com/en/posts/agent-playwright-cloak/