lelii
/
dev-mcps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
dev-mcps/browser-mcp/README.md

2.1 KiB
Raw Blame History

browser-mcp

Playwright browser automation exposed only through MCP Streamable HTTP.

Security properties

  • Exact-origin allowlist for top-level navigation and every intercepted HTTP(S) request.
  • No filesystem/workspace mount.
  • No arbitrary JavaScript evaluation, file upload, download, shell, or CDP tool.
  • One isolated browser context per MCP session, destroyed when the session expires or is deleted.
  • Bounded screenshots, text snapshots, console logs, network errors, request bodies, and session counts.
  • API authentication is mandatory and browser-origin CORS is denied unless explicitly allowlisted.

The container runs as pwuser with the Chromium sandbox enabled. The stack applies Playwright’s official default-derived seccomp_profile.json, which permits the user-namespace calls required by the sandbox, and restores only SYS_CHROOT after dropping every capability. Keep the container on an internal network that can reach only the development application. This is a hardened browser worker, not a VM-grade boundary.

Tools

browser_navigate, browser_click, browser_fill, browser_wait, browser_snapshot, browser_screenshot, browser_console_messages, and browser_network_errors.

Configuration

Required environment variables:

  • BROWSER_MCP_API_KEYS: comma-separated SUBJECT=TOKEN values; tokens must contain at least 32 characters.
  • BROWSER_MCP_ALLOWED_ORIGINS: comma-separated exact origins, for example http://dev-server-worker:5173. An entry may carry a port range instead of a port — http://dev-server-worker:5200-5219 — which is how one entry covers every port the dev server may hand to an execution. The host still has to match exactly; only the port varies, and only inside the declared range. An impossible range is refused at startup rather than at the first navigation.

The MCP endpoint is POST /mcp. Initialize first and reuse the returned Mcp-Session-Id. Only Streamable HTTP is implemented; there is no legacy SSE or stdio transport.

Run npm install and npm test for local tests. The provided image already contains the matching Chromium build.