Secure Browser MCP

Secure Browser MCP

An MCP server that gives an AI client (Claude, etc.) controlled access to a realheadless browser on your server — with domain allowlisting, SSRF protection,per-session isolation, an audit log, and cookies/state that survive restarts.

Why "secure" specifically

Browser-automation MCPs are risky by default because the LLM effectively getsa pair of hands on a live browser that can reach anywhere on the internet(and, if misconfigured, your internal network). This server closes thecommon holes:

This covers the common attack surface, but you're still exposing a browser toan LLM. Keep ALLOWED_DOMAINS as narrow as your task allows, and run this ona host/container with no access to anything sensitive — treat it like youwould a CI runner that executes untrusted code.

Persistent storage — what's actually persisted

Two things, both in SQLite at ./data/browser-mcp.db (path configurable viaDATA_DIR):

1. Browser state — cookies + localStorage per session, captured viaPlaywright's storageState() and restored on the next browser_navigatecall for that sessionId. This is what lets a session stay logged in toa site across server restarts. Call browser_persist_session to saveexplicitly, or browser_close_session (which persists automatically).
2. Audit log — every tool invocation, its params, and outcome, so youcan review what the browser actually did later (browser_audit_log).

If you'd rather keep this in Supabase instead of local SQLite (e.g. somultiple server instances share state), swap storage.ts for Supabase calls— the function signatures are small and self-contained, so it's a drop-inreplacement.

Setup

npm install
npx playwright install --with-deps chromium   # downloads the browser binary
cp .env.example .env
# edit .env: set MCP_AUTH_TOKEN and ALLOWED_DOMAINS
npm run build
npm start

For local iteration without building: npm run dev.

The server listens on POST http://localhost:8787/mcp (Streamable HTTPtransport). Point your MCP client at that URL with:

Authorization: Bearer <your MCP_AUTH_TOKEN>

Tools exposed

• browser_navigate(sessionId, url) — allowlist + SSRF-checked navigation
• browser_get_text(sessionId, selector?) — read page/element text
• browser_click(sessionId, selector)
• browser_type(sessionId, selector, text)
• browser_screenshot(sessionId) — base64 PNG
• browser_persist_session(sessionId) — force-save cookies/localStorage
• browser_close_session(sessionId) — persist + free browser resources
• browser_list_sessions()
• browser_audit_log(sessionId, limit?)

sessionId is any string you choose (e.g. "pranav-github-login") — reusethe same one to keep continuity (logged-in state, cookies) across calls.

Deploying on your existing server

• Render: same pattern you used for the MongoDB MCP — set env vars inthe dashboard (don't bake MCP_AUTH_TOKEN into the image), expose port8787, and set the health check to GET /mcp returning 401 (expected,since it's unauthenticated) rather than a 200.
• Put this behind HTTPS (Render/most PaaS do this for you) — the bearertoken is meaningless over plain HTTP.
• If the server also hosts other things, run this in its own container sothe idle-session reaper and MAX_SESSIONS cap actually bound its resourceuse independently.

Extending

• To let the LLM choose domains dynamically instead of a static allowlist,add an approval step (return a tool result asking for confirmation) ratherthan opening ALLOWED_DOMAINS wide.
• To persist to Supabase instead of SQLite, replace the functions insrc/storage.ts; the audit log schema maps directly to a Postgres table.
• The MCP TypeScript SDK evolves — if npm install pulls a version with adifferent StreamableHTTPServerTransport API, checkhttps://github.com/modelcontextprotocol/typescript-sdk for the currentsignature.