Skip to main content
Glama
mickadoua

guarded-browser-mcp

by mickadoua
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

guarded-browser-mcp

An MCP server that lets an AI agent drive a self-hosted Chromium, with guardrails enforced by the server itself rather than by the agent's instructions.

Built for a personal assistant: filling in online forms, preparing purchases, reading pages, while the human watches the same browser live and takes over whenever needed (login, two-factor authentication, captcha).

Guardrails

Guardrail

Effect

Allowed / denied sites

Domain allowlist or denylist per session. Any navigation to a refused domain is blocked inside the browser, including after a redirect or within a frame. The denylist always wins.

Separate final action

click refuses buttons that send, submit, pay or order. Only submit_final triggers them: set it to "ask first" in your MCP client or gateway, and every submission waits for human approval.

Sensitive fields

type_text refuses password, payment card, IBAN and one-time-code fields. The human fills them in directly in the browser.

Isolated sessions

Each access token has its own browser context (cookies, logins, rules). A token never drives another session. Several sessions can share one Chromium.

Untrusted content

Page text is returned as data, never as instructions.

Site rules are re-read on every call: edit them without restarting.

Related MCP server: farr-browser-mcp

Tools

Tool

Effect

open_url

open a URL if the site is allowed

read_page

title, URL, visible text and numbered actionable elements

screenshot

PNG screenshot

click

click a numbered element, unless it is a final action

type_text

fill in a field, unless it is sensitive

select_option

pick an option in a dropdown

submit_final

trigger a final action, with a summary of what goes out

sites

rules in force for the session (read-only)

Architecture

agent ──MCP + token──▶ guarded-browser-mcp ──CDP (secret path)──▶ nginx gate ──▶ Chromium (one session)
                                                                                   ▲
human ──web UI (KasmVNC, behind your authentication)──────────────────────────────┘

  • Chromium (linuxserver/chromium image) serves a web UI and keeps its profile on disk.

  • Chrome only accepts remote debugging on 127.0.0.1: a small nginx gate sharing its network namespace exposes it on a secret path, with access logging disabled.

  • guarded-browser-mcp uses Playwright over CDP: no browser is bundled in its image.

Setup

  1. Copy deploy/compose.example.yaml, sessions.example.yaml to sessions.yaml, and policies/example.yaml to policies/<session>.yaml.

  2. In .env, generate long random values: BROWSER_PASSWORD, CDP_TOKEN_ASSISTANT, MCP_TOKEN_ASSISTANT (32 characters minimum).

  3. docker compose up -d.

  4. Publish the browser web UI (port 3000) only behind strong authentication, never in the clear on the Internet. Never publish the CDP port. Publish the MCP server only behind an authenticating proxy (for example a tunnel with a service token), in addition to its bearer token.

  5. Register the server in your MCP client: streamable HTTP transport, path /mcp, header Authorization: Bearer <MCP_TOKEN_ASSISTANT>. Set submit_final to "ask first".

Several sessions

Two ways to add a session, both declared in sessions.yaml with their own token and rules:

  • Same Chromium, isolated context (isolated: true): light, no new container. The session gets a fresh browser context with its own cookies, invisible to other sessions. Its cookies and local storage are saved to STATE_DIR/<session>.json (mode 600) after every call and restored when Chromium restarts. Session storage and IndexedDB are not kept. Its windows show up in the shared web UI, so a human can log in there.

  • Dedicated Chromium: duplicate the browser and gate services and add their two variables. Full isolation, including the web UI, at the cost of one more browser in memory.

At most one session per Chromium can use the browser's own profile (no isolated).

Recommendations

  • Only log in to the sites the agent needs in a session. Never your bank or your mailbox: whoever drives the browser acts on your behalf on every logged-in site.

  • Prefer allowlist mode.

  • Some sites detect automation: the human then finishes in the web UI.

License

MIT

This server cannot be deployed

Let your AI agent see the webWeb-to-screenshot MCP for Claude, Cursor and Codex. No cookie banners. Free to start.snap-render.comAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Playwright MCP Server

    tomscoppock
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents and clients to control a real Chromium browser through MCP tool calls, including navigation, clicking, typing, JavaScript evaluation, screenshots, and DOM snapshots. Supports multiple isolated sessions over authenticated HTTP with no disk writes.
    Apache 2.0

  • farr-browser-mcp

    kiomarssharifi
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents to drive a live Chromium browser through MCP tools for reading pages as markdown, clicking and typing with element refs, taking screenshots, and downloading files, while enforcing safety rules like stale-ref refusal, irreversible-action blocking, robots.txt compliance, request pacing, and configurable proxies. It also supports site skills for structured data extraction.
    Apache 2.0

  • tablaze

    SweetDianDian
    A
    license
    A
    quality
    B
    maintenance
    Enables AI agents to drive a Chromium browser through MCP, with persistent sessions, compact page snapshots, guarded actions, batched operations, and explicit result verification.
    16
    MIT

  • webpilot

    GustavoPFARIA
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables MCP clients such as Claude Desktop, Claude Code and IDE agents to call a tool that drives a real Playwright browser to complete web tasks, with sensitive actions automatically refused when no human is available to approve them.
    MIT