Auto Browser
MCP-native browser control plane with human takeover, reusable auth profiles, approvals, and audit trails.
Add to your client
Copy the config for your MCP client and paste it into its config file.
uvx auto-browser-mcpPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"auto-browser": {
"command": "uvx",
"args": [
"auto-browser-mcp"
],
"env": {
"AUTO_BROWSER_BASE_URL": "http://127.0.0.1:8000/mcp",
"AUTO_BROWSER_BEARER_TOKEN": ""
}
}
}
}Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.
Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- Docker and Docker Compose to run the controller and browser-node stack locally
- The Auto Browser controller running and reachable at http://127.0.0.1:8000/mcp
- uv / uvx installed to run the stdio bridge via `uvx auto-browser-mcp` (or Python 3.10+ to run scripts/mcp_stdio_bridge.py from a checkout)
- An MCP client such as Claude Desktop or Cursor
About Auto Browser
Auto Browser packages a Playwright-backed browser as an MCP-native control plane. MCP clients, LLM agents, and human operators share the same live browser session: agents drive it through MCP tools while a human can take over through noVNC when a site gets brittle. It adds reusable named auth profiles (log in once, reopen pre-authenticated sessions), approval gates, operator identity headers, audit events, PII scrubbing, and verifiable hash-chained Witness receipts. The stack runs locally via Docker Compose (controller + browser-node) and exposes an HTTP MCP endpoint, a stdio bridge, and a REST API. A curated MCP tool profile is the default for clean tool selection; a full profile exposes agent-queue and convergence-harness tools for governed skill induction.
Tools & capabilities (12)
browser.create_sessionCreate a new browser session, optionally with a name, start_url, and a saved auth_profile to resume pre-authenticated.
browser.list_sessionsList active browser sessions.
browser.verify_witnessRead-only tool that walks the full hash-chained Witness receipt log for a session and reports the first divergent receipt if the log was altered, reordered, or truncated.
harness.list_runsRead-only convergence-harness tool (curated profile) to list harness runs.
harness.get_statusRead-only convergence-harness tool (curated profile) to inspect the status of a harness run.
harness.get_traceRead-only convergence-harness tool (curated profile) to fetch the recorded trace of a harness run.
harness.start_convergenceFull-profile tool that starts a convergence run against a live browser session (use workflow_profile=governed).
harness.list_candidatesFull-profile tool to list staged skill candidates produced by convergence runs.
harness.get_candidateFull-profile tool to fetch a staged skill candidate.
harness.graduateFull-profile tool that writes a staged skill candidate with signed provenance; promotion to the production corpus remains a separate governed review step.
browser.queue_agent_runFull-profile tool that queues a background agent run; accepts workflow_profile (fast or governed).
browser.resume_agent_jobFull-profile tool that resumes interrupted, failed, or step-limited background runs from persisted checkpoints.
What this server can do
Auto Browser provides tools for these capabilities — tap one to see every MCP server that does the same:
When to use it
- Login-once, reuse-later account workflows by saving a named auth profile and opening fresh pre-authenticated sessions
- Operator-assisted QA and browser debugging where a human can take over a brittle flow via noVNC
- MCP-powered agent workflows that need a real browser rather than plain HTML fetches
- Internal dashboards and admin tools driven by an AI agent with approval gates and audit trails
- Governed agent skill induction: turning verified, tamper-checked browser traces into staged skill candidates
Security notes
The MCP stdio bridge proxies the client to the local controller at http://127.0.0.1:8000/mcp; all published ports bind to 127.0.0.1 by default. The example config leaves AUTO_BROWSER_BEARER_TOKEN empty for local development. For real private deployments the README recommends setting APP_ENV=production, a strong API_BEARER_TOKEN (and the matching AUTO_BROWSER_BEARER_TOKEN on the bridge), REQUIRE_OPERATOR_ID=true, AUTH_STATE_ENCRYPTION_KEY (44-char Fernet) with REQUIRE_AUTH_STATE_ENCRYPTION=true, REQUEST_RATE_LIMIT_ENABLED=true, METRICS_ENABLED=true, and STEALTH_ENABLED=false. COMPLIANCE_TEMPLATE (strict or balanced) can apply a hardened posture at startup. Authorized workflows only; the project explicitly does not support CAPTCHA solving, unauthorized scraping, or bypass tooling.
Auto Browser FAQ
How does an MCP client connect to Auto Browser?
Start the stack locally (docker compose up --build), then point a stdio-first client like Claude Desktop at the bundled bridge via `uvx auto-browser-mcp`, with AUTO_BROWSER_BASE_URL set to http://127.0.0.1:8000/mcp. HTTP-capable clients can talk to the /mcp endpoint directly.
Which tools are available by default?
The default MCP_TOOL_PROFILE is `curated`, which keeps the browser surface compact and hides approval-admin, agent-queue, provider-introspection, and remote-access-admin tools. Read-only harness inspection tools are included. Set MCP_TOOL_PROFILE=full to expose the full surface, including harness.* convergence tools and the agent-queue tools.
How do I secure a non-local deployment?
Set APP_ENV=production, a strong API_BEARER_TOKEN (and the matching AUTO_BROWSER_BEARER_TOKEN on the bridge), REQUIRE_OPERATOR_ID=true, AUTH_STATE_ENCRYPTION_KEY with REQUIRE_AUTH_STATE_ENCRYPTION=true, rate limiting, and metrics. COMPLIANCE_TEMPLATE=strict or =balanced applies a preconfigured posture at startup.
What is Auto Browser not meant for?
It explicitly does not target CAPTCHA solving, unauthorized scraping or account automation, or deceptive identity shaping / bypass tooling. It is built for authorized, human-in-the-loop workflows.
Alternatives to Auto Browser
Compare all alternatives →
All-in-one web access MCP — Web Unlocker, SERP, Scraper API, and a cloud Scraping Browser.
Popular community Playwright + API testing MCP server with codegen, screenshots, and device emulation.
Official Browserbase cloud-browser MCP built on Stagehand — natural-language act/extract/observe.
Compare Auto Browser with: