mcp-browser

mcp-browser

A production-grade FastMCP server that exposes Playwright browser automation as MCP tools — letting Claude (or any MCP client) drive a real browser tab-by-tab without ever touching the user's active session.

Built and used daily as part of an autonomous agentic fleet that fills forms, navigates sites, applies to jobs, and manages profiles — all via Claude tool calls.

What's inside

30+ pw_* browser primitives

Every tool follows the same contract: target a specific tab (page_index or page_url), never tab 0 (the user's active tab). Returns structured JSON — no raw HTML noise.

Arc browser tab management

Tools for inspecting and driving Arc tabs by space/title/URL — works alongside the pw_* primitives.

Compiled recipes

A pw_recipe dispatcher that runs pre-verified multi-step flows without burning schema tokens. Two examples included:

• the_internet/login — canonical UI-automation sandbox (deterministic creds, read-only)
• wikipedia/summary — fetch an article summary

Architecture

server.py                 ← 3-line FastMCP entry point
server_base.py            ← factory: auto-discovers tools + starts file watcher
tools_registry.py         ← walks tools/ and registers every non-private function

tools/
  browser/
    config.py             ← MCP_PLAYWRIGHT_RUNTIME env var (path to Node runtime)
    recipe.py             ← pw_recipe dispatcher
    playwright/
      _cdp.py             ← persistent CDP daemon bridge (one connectOverCDP per session)
      _resolve_page.py    ← shared JS: resolve page by index or URL substring
      cdp_daemon.js       ← long-lived Node daemon; reuses the CDP connection across calls
      pw_*.py             ← one file per tool; auto-registered at startup
    arc/
      *.py                ← Arc-specific tab management tools
  recipes/
    the_internet/login.py
    wikipedia/summary.py
playwright-runtime/
  package.json            ← { "dependencies": { "playwright": "^1.58.2" } }

The CDP daemon

By default every Playwright tool would spawn a fresh node -e process, pay a full connectOverCDP handshake, and enumerate all tabs — adding ~300–800 ms per call. The daemon (cdp_daemon.js) holds one live CDP connection and routes action bodies to it over HTTP on localhost:9224. Result: per-call overhead drops to near zero; the first call pays the startup cost, every subsequent one is just the action.

The daemon is started lazily on the first tool call and exits after 10 minutes idle.

Auto-discovery

tools_registry.py walks tools/ at startup and registers every non-underscore .py file as an MCP tool — no explicit imports, no decorator boilerplate. Add a new tool file → it's live on the next hot-reload (via mcp-hmr).

Setup

Prerequisites

• Python 3.10+
• Node.js 18+
• A Chromium-family browser running with --remote-debugging-port=9222(Arc on macOS does this automatically; for others: chromium --remote-debugging-port=9222)

Install

# Python deps
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt

# Node Playwright runtime
cd playwright-runtime && npm install && cd ..

Register with Claude

Add to your claude_desktop_config.json (or equivalent MCP config):

{
  "mcpServers": {
    "mcp-browser": {
      "command": "/path/to/venv/bin/python",
      "args": ["-m", "server"],
      "cwd": "/path/to/mcp-browser",
      "env": {
        "MCP_PLAYWRIGHT_RUNTIME": "/path/to/mcp-browser/playwright-runtime"
      }
    }
  }
}

Run standalone

python server.py

Usage pattern

A typical Claude interaction:

# 1. Open a new worker tab (never hijack tab 0 — that's the user's view)
pw_new_tab() → { page_index: 3 }

# 2. Navigate
pw_goto(url="https://example.com/login", page_index=3)

# 3. Inspect what's actionable
pw_snapshot(page_index=3)  → { elements: [ { tag: "input", label: "Email", selector: "#email" }, ... ] }

# 4. Fill and submit
pw_fill(selector="#email", value="[email protected]", page_index=3)
pw_fill(selector="#password", value="...", page_index=3)
pw_click(selector="button[type='submit']", page_index=3)

# 5. Verify
pw_get_text(selector=".dashboard-header", page_index=3)

Or run the whole flow in one call with pw_act:

pw_act(steps=[
    {"goto": "https://example.com/login"},
    {"fill": "#email", "value": "[email protected]"},
    {"fill": "#password", "value": "..."},
    {"click": "button[type='submit']"},
    {"wait_for": ".dashboard-header"},
    {"text": ".dashboard-header"},
], new_tab=True)

Design decisions

Tab 0 is sacred. Every tool refuses to default to tab 0. The user's active tab must never be hijacked mid-session — this is a hard invariant, not a convention.

One tool = one file. Each pw_*.py is a standalone module with a single exported function. Auto-discovery means adding a tool is as simple as dropping a new file.

JSON in, JSON out. Every tool returns { status: "ok"|"error", ... }. No exceptions surface as unhandled Python tracebacks.

pw_act for multi-step flows. N round-trips of goto → fill → click → snapshot cost N × (model latency + daemon call). pw_act collapses them into 1 — especially valuable in agentic loops.

License

MIT