30 lines
2.1 KiB
Markdown
30 lines
2.1 KiB
Markdown
# 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.
|