Skip to content
Back to search

browser-guard-mcp

Capability-scoped browser access for MCP agents: public-only navigation, one-use approval for secrets, and in-memory evidence.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/alexandryasukaitisss-cmd--browser-guard-mcp/badge.svg)](/listings/alexandryasukaitisss-cmd--browser-guard-mcp)

HTML

<a href="/listings/alexandryasukaitisss-cmd--browser-guard-mcp"><img src="/api/listings/alexandryasukaitisss-cmd--browser-guard-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requirements:

- Node.js 20 or newer. - Google Chrome. - [`@playwright/mcp`](https://github.com/microsoft/playwright-mcp) 0.0.76 or newer.

git clone https://github.com/alexandryasukaitisss-cmd/browser-guard-mcp.git
cd browser-guard-mcp
npm test

Install Playwright MCP and note the absolute path to its CLI:

npm install -g @playwright/mcp
npm root -g
# <npm-root>/@playwright/mcp/cli.js

Create a guard configuration:

mkdir -p ~/.config/browser-guard-mcp
cp examples/config.example.json ~/.config/browser-guard-mcp/config.json

Edit these values:

- `runtimeDir`: a private state directory. The guard creates it with mode `0700`. - `chrome.nodeCommand`: the Node binary that starts Playwright MCP. Defaults to the current Node process if omitted. - `chrome.playwrightCli`: the absolute path printed by `npm root -g`. - `capabilities`: the profiles described below.

Check that the configuration loads:

node src/cli.cjs --check --config ~/.config/browser-guard-mcp/config.json

Add the server to your MCP client. See [`examples/mcp-client.json`](examples/mcp-client.json):

{
  "mcpServers": {
    "browser-guard": {
      "command": "/usr/local/bin/node",
      "args": [
        "/Users/you/src/browser-guard-mcp/src/cli.cjs",
        "--config",
        "/Users/you/.config/browser-guard-mcp/config.json"
      ]
    }
  }
}

Restart the client and ask:

> Open `https://example.com` and summarize it. Use `browser_route_open` with `intent: "read"`.

For interaction, activate a profile that permits it first:

> Call `browser_capability_activate` with `profile_id: "public-interact"`, open `https://github.com`, and click the search field.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 205 lines
  1. # Browser Guard MCP
  2. **Give your agent a browser, not your browser.**
  3. An MCP server that gives a coding agent a controlled Chromium session: public pages only, explicit capability profiles, one-use approval for card/password/one-time-code entry, and evidence that stays in process memory.
  4. The guard starts its own isolated headless Chrome. It does not attach to your desktop browser, inherit your cookies, load your extensions, or expose a general-purpose browser API. Every action goes through one narrow, auditable surface.
  5. Version 0.1.0. macOS-first; the sensitive-input dialog currently uses `osascript`.
  6. Русская версия: [README.ru.md](README.ru.md).
  7. ## Why
  8. Coding agents increasingly need to click, fill, and read real pages. Handing them the user's browser also hands them sessions, saved passwords, extensions, and the local network. This guard exposes the useful part and keeps the rest out of reach.
  9. ## Quick start
  10. Requirements:
  11. - Node.js 20 or newer.
  12. - Google Chrome.
  13. - [`@playwright/mcp`](https://github.com/microsoft/playwright-mcp) 0.0.76 or newer.
  14. ```sh
  15. git clone https://github.com/alexandryasukaitisss-cmd/browser-guard-mcp.git
  16. cd browser-guard-mcp
  17. npm test
  18. ```
  19. Install Playwright MCP and note the absolute path to its CLI:
  20. ```sh
  21. npm install -g @playwright/mcp
  22. npm root -g
  23. # <npm-root>/@playwright/mcp/cli.js
  24. ```
  25. Create a guard configuration:
  26. ```sh
  27. mkdir -p ~/.config/browser-guard-mcp
  28. cp examples/config.example.json ~/.config/browser-guard-mcp/config.json
  29. ```
  30. Edit these values:
  31. - `runtimeDir`: a private state directory. The guard creates it with mode `0700`.
  32. - `chrome.nodeCommand`: the Node binary that starts Playwright MCP. Defaults to the current Node process if omitted.
  33. - `chrome.playwrightCli`: the absolute path printed by `npm root -g`.
  34. - `capabilities`: the profiles described below.
  35. Check that the configuration loads:
  36. ```sh
  37. node src/cli.cjs --check --config ~/.config/browser-guard-mcp/config.json
  38. ```
  39. Add the server to your MCP client. See [`examples/mcp-client.json`](examples/mcp-client.json):
  40. ```json
  41. {
  42. "mcpServers": {
  43. "browser-guard": {
  44. "command": "/usr/local/bin/node",
  45. "args": [
  46. "/Users/you/src/browser-guard-mcp/src/cli.cjs",
  47. "--config",
  48. "/Users/you/.config/browser-guard-mcp/config.json"
  49. ]
  50. }
  51. }
  52. }
  53. ```
  54. Restart the client and ask:
  55. > Open `https://example.com` and summarize it. Use `browser_route_open` with `intent: "read"`.
  56. For interaction, activate a profile that permits it first:
  57. > Call `browser_capability_activate` with `profile_id: "public-interact"`, open `https://github.com`, and click the search field.
  58. ## Tools
  59. The server exposes nine guard tools. It does not expose raw `browser_*` tools.
  60. | Tool | Purpose |
  61. | --- | --- |
  62. | `browser_route_open` | Open a public HTTP(S) URL. `intent` is `read`, `extract`, `visual`, or `interactive`. |
  63. | `browser_route_call` | Call an allow-listed operation on the active page. |
  64. | `browser_capability_activate` | Activate a configured profile for a bounded lifetime. |
  65. | `browser_capability_status` | Show the active profile and expiry. No page data. |
  66. | `browser_action_prepare` | Create a one-use action ID; ask for native approval only for sensitive input. |
  67. | `browser_evidence_bundle` | Capture a bounded snapshot and console output into memory. |
  68. | `browser_evidence_get` | Read an unexpired in-memory bundle. |
  69. | `browser_guard_status` | Show backend and capability state. No page data. |
  70. | `browser_compatibility_summary` | Show the content-free local ledger summary. |
  71. `browser_route_call` accepts only these operations:
  72. | Operation | Profile permission |
  73. | --- | --- |
  74. | `browser_navigate`, `browser_navigate_back` | `navigate` |
  75. | `browser_snapshot` | `read` |
  76. | `browser_console_messages`, `browser_wait_for`, `browser_close` | `observe` |
  77. | `browser_click`, `browser_hover`, `browser_type`, `browser_press_key`, `browser_select_option`, `browser_fill_form`, `browser_file_upload` | `interact` |
  78. Everything else is denied. That includes JavaScript evaluation, arbitrary code, cookies, storage, tabs, network-request inspection, and screenshots.
  79. ## Capability profiles
  80. A profile names DNS host patterns, allowed operations, and a maximum lifetime. The default profile is `public-read`: navigation and reading, no interaction.
  81. ```json
  82. {
  83. "defaultProfile": "public-read",
  84. "profiles": [
  85. {
  86. "id": "public-interact",
  87. "hosts": ["github.com", "*.github.com"],
  88. "operations": ["navigate", "read", "extract", "observe", "interact"],
  89. "maxTtlSeconds": 900
  90. }
  91. ]
  92. }
  93. ```
  94. Host patterns support `*`, an exact host, or `*.subdomain`. IP addresses are rejected as patterns. A grant is held in memory and expires; restarting the guard clears it.
  95. ## Sensitive input
  96. Before typing into a card number, password, or one-time-code field, the agent must:
  97. 1. Call `browser_action_prepare` with the exact tool and arguments.
  98. 2. The guard shows a native macOS dialog with **Deny** as the default. Approval returns a one-use ID.
  99. 3. Pass that ID to `browser_route_call` with the same tool and arguments.
  100. The ID is bound to the grant, exact origin, tool name, and a SHA-256 digest of the arguments. It expires after 60 seconds by default. Reuse, argument changes, or an origin change fail closed. On non-macOS systems the dialog cannot be shown, so sensitive input is denied.
  101. Detection uses explicit field metadata: `type=password`, card/OTP `autocomplete` tokens, and labels such as “Card number”, “CVV”, “Password”, “One-time code”, “Номер карты”, or “Пароль”.
  102. **It can miss a field.** A custom widget, a field labeled only “Verification code”, or an incomplete agent description may not trigger the dialog. Treat the approval as a guard against accidental entry, not as a data-loss-prevention control. Do not give the agent real card data. The full boundary is below.
  103. ## Evidence and local audit
  104. - `browser_evidence_bundle` keeps a bounded snapshot and console output in process memory. It expires with the capability grant and never becomes a file managed by the guard.
  105. - The compatibility ledger is a local JSONL file with mode `0600`. It records only: timestamp, operation, backend, intent, success/failure, error category, operation class, duration bucket, coarse client class, and upload file count. It does not record URLs, domains, page text, arguments, screenshots, cookies, or confirmation IDs.
  106. - Playwright may write transient snapshot files under the private runtime output directory. The guard removes that directory when it closes. The ledger is separate and content-free.
  107. ## Demo
  108. ```sh
  109. PLAYWRIGHT_MCP_CLI="$(npm root -g)/@playwright/mcp/cli.js" node demo/blocked.cjs
  110. ```
  111. Expected shape:
  112. ```text
  113. public page: https://example.com/ via chrome
  114. loopback: NETWORK_DENIED
  115. local server requests: 0
  116. ```
  117. The local server is real. The last line is the point: the request never arrived.
  118. ## Security boundary
  119. What the guard enforces:
  120. - HTTP(S) only, standard ports 80/443, no credentials in the URL.
  121. - Literal private, loopback, link-local, multicast, and special-use addresses are rejected before navigation.
  122. - All Chromium traffic goes through a loopback egress proxy. The proxy resolves each hostname, rejects non-public results, reapplies the active capability host patterns, and covers redirects and subresources.
  123. - Chrome runs with `--isolated`, a private profile, no storage state, no service workers, and a minimal environment without ambient proxy variables or credentials.
  124. - Only the allow-listed operations above reach the browser.
  125. - Known secret files cannot be uploaded: `.env*` (except examples), private keys, Keychain data, `auth.json`, `.ssh`, `.aws`, `.kube`, and similar locations, after `realpath`.
  126. - Card, password, and one-time-code input needs a one-use native approval.
  127. What it does not enforce:
  128. - It is not an operating-system sandbox. Chromium runs with your user privileges. A browser-engine exploit is outside this design.
  129. - Public pages can still be malicious, misleading, or hostile. The guard controls reachability, not content.
  130. - The egress proxy is a boundary for HTTP(S) traffic, not proof against every side channel (for example WebRTC, QUIC, or browser bugs).
  131. - Sensitive-field detection is heuristic. A field with an unusual label can be missed. Do not treat the dialog as a guarantee that no secret can ever be typed.
  132. - Upload checks inspect paths and names, not file contents.
  133. - The isolated profile has no logged-in sessions. Sites that require your existing login will not work; that is intentional.
  134. - Playwright and Chromium keep their own behavior and output. This project does not audit or patch them.
  135. The full boundary and residual risks are in [docs/threat-model.md](docs/threat-model.md). The architecture is in [docs/design.md](docs/design.md).
  136. Report security issues privately as described in [SECURITY.md](SECURITY.md).
  137. ## Development
  138. ```sh
  139. npm test # 45 deterministic tests, no browser
  140. npm run check # validate the example configuration
  141. npm run smoke -- --config /path/to/config.json
  142. ```
  143. The live smoke needs Chrome, Playwright MCP, and outbound network access. It opens a public page, captures in-memory evidence, and verifies that a loopback route is denied.
  144. ## License
  145. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.