lelii
/
dev-mcps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
dev-mcps/browser-mcp
History
Lucio Lelii deb3d81119 Keep the MCP servers' code here and deploy them from another repository 
The compose files, the gateway's Caddyfiles, the egress proxy's configuration, the example
.env, the seccomp profile, the dev-server's example service definitions and the stack's two
documents moved to mcps-docker-compose. With the images published to Docker Hub, a server
runs them without the sources, and a deploy is a new image tag; keeping both here meant the
repository that changes with the code also carried what only changes when a host does.

publish-images.sh builds the four images for amd64 and arm64 and pushes them tagged with
this repository's commit hash and "latest". It refuses a dirty working tree, since the
tag names a commit. The images now published were built from 921d54c.

Each server keeps its README and tests, and coding-agent-mcp its own standalone compose
files. The three references that pointed at moved files now say where they went.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
 		2026-10-02 11:49:09 +02:00
..
src Bring the three MCP servers together as one deployable stack 2026-09-22 11:45:55 +02:00
test Bring the three MCP servers together as one deployable stack 2026-09-22 11:45:55 +02:00
.dockerignore Bring the three MCP servers together as one deployable stack 2026-09-22 11:45:55 +02:00
.gitignore Bring the three MCP servers together as one deployable stack 2026-09-22 11:45:55 +02:00
Dockerfile Keep the MCP servers' code here and deploy them from another repository 2026-10-02 11:49:09 +02:00
README.md Keep the MCP servers' code here and deploy them from another repository 2026-10-02 11:49:09 +02:00
package-lock.json Bring the three MCP servers together as one deployable stack 2026-09-22 11:45:55 +02:00
package.json Bring the three MCP servers together as one deployable stack 2026-09-22 11:45:55 +02:00

README.md

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 (the mcps-docker-compose repository) 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.