Zendriver MCP

A Model Context Protocol server that gives an AI agent a real, headed Chrome, driven over the Chrome DevTools Protocol through zendriver, and built so the page it is looking at cannot tell an agent is there.

• 98 browser tools behind a small fixed tool list: navigation, elements, forms, tabs, cookies and storage, network logs and mocking, emulation, accessibility, tracing, Lighthouse, screencasts and more.

• Hard to detect by design. Helper scripts and element ids live in an isolated JavaScript world, nothing is written into the DOM, and clicks and keys are trusted input events.

• Built for the current MCP spec. It serves 2026-07-28 and the 2025 handshake versions from one server. Every tool returns structured results, carries annotations, and fails with an error code and a recovery hint.

Contents

• Quick start

• How an agent uses it

• Tools

• What a page can and cannot see

• Configuration

• Running over HTTP

• Protocol support

• Architecture

• Development

• Acknowledgements

• License

Related MCP server: puppeteer-real-browser-mcp-server

Quick start

Requirements: Python 3.10+, Google Chrome or Chromium, and a display. On a headless Linux host, run Xvfb (Xvfb :99 & and DISPLAY=:99). The server never runs Chrome headless; see why.

Claude Code

claude mcp add browser -- uvx --from git+https://github.com/coffeegrind123/zendriver-mcp-next zendriver-mcp

Any MCP client (stdio):

{
  "mcpServers": {
    "browser": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/coffeegrind123/zendriver-mcp-next", "zendriver-mcp"],
      "env": { "DISPLAY": ":99" }
    }
  }
}

From a checkout

git clone https://github.com/coffeegrind123/zendriver-mcp-next
cd zendriver-mcp-next
uv sync
uv run zendriver-mcp            # stdio
uv run zendriver-mcp --help     # transports, tokens, options

How an agent uses it

The server sends the model short instructions when it connects. The core loop is:

start_browser → navigate(url) → get_interaction_tree → click / type_text / press_key
             → get_text_content or screenshot → stop_browser

• navigate waits for the page to settle. It waits for document.readyState to reach complete, then for the network to go idle, and reports which of the two happened.

• Elements are addressed by CSS selector, or by the numeric id that get_interaction_tree assigns. Ids stay valid while the element exists. A stale id fails with code stale_id instead of hitting the wrong element.

• Tabs. Every page tool takes an optional tab="tab_2", which acts on that tab for one call without switching to it. Tabs the page opens itself (popups, target=_blank) are picked up automatically.

• Everything else is one search away. search_tools("block requests") finds the tool, and call_tool runs it.

• batch runs a known sequence in one call. A later step can read an earlier result as "$N.field", or as "${N.field}" inside a longer string.

• jobs runs a slow tool in the background (Lighthouse, heap snapshots, video export) and records its progress.

Every result has structured content plus a text summary. Every failure is an isError result shaped like this:

{ "error": "Something covers #buy at (640, 412): <div#cookie-banner>.",
  "code": "element_obscured",
  "hint": "Close the overlay on top (a cookie banner, a modal) or scroll so the element is unobstructed. force=true clicks at that point anyway." }

Tools

The default tools/list has 19 entries: the core loop below, plus search_tools, describe_tool, call_tool, batch and jobs. The core tools are tagged anthropic/alwaysLoad so that Claude Code's tool search never defers them. Set ZENDRIVER_MCP_SURFACE=full to list all 103 directly.

The full list, with each tool's effect, parameters and summary, is in docs/tools.md. That file is generated from the code.

Resources. Files that tools write are served back as resources, so a remote client can fetch them:

• browser://artifacts/{name}: screenshots, traces, heap snapshots, videos, cookie exports;

• browser://tabs;

• browser://tabs/{tab}/info, /console and /network.

{tab} and {name} support completion. On 2026-07-28 clients, opening or closing a tab publishes resources/list_changed to subscriptions/listen streams.

Prompts. read_page, fill_form_task and audit_page.

What a page can and cannot see

Pages detect automation by looking for side effects. Each row below is a side effect that other CDP tools leave behind and this server avoids. Each claim is checked by the live test in tests/test_live.py, which records events from a listener inside the page itself.

The remaining exposure is documented, not hidden:

• execute_js runs in the page's own world by design. Prefer the dedicated tools.

• select_option sets a native <select> by script, so its change event is untrusted. For a trusted change, focus the select and use press_key.

• start_browser(low_memory=true) adds container-friendly flags such as --disable-gpu, which produce detectable software WebGL. Use it only where Chrome cannot start without it.

Configuration

All settings are optional environment variables.

ZENDRIVER_MCP_GATEWAY=1 and ZENDRIVER_MCP_PROFILE=gateway are still accepted, and mean SURFACE=catalog.

Running over HTTP

stdio gives each client its own browser. To let several clients share one long-lived browser, use Streamable HTTP:

zendriver-mcp --create-token laptop        # prints the token once; only its hash is stored
zendriver-mcp --transport streamable-http --host 127.0.0.1 --port 8931
claude mcp add --transport http browser http://127.0.0.1:8931/mcp \
  --header "Authorization: Bearer zmcp_..."

• Tokens. Bearer tokens are compared in constant time and stored as SHA-256 hashes with mode 0600. Each token's name becomes the caller identity, so one client cannot see or drive another client's tabs.

• Without tokens. The server runs unauthenticated on loopback only. It refuses to bind any other address.

• Host and Origin checks protect against DNS rebinding. Add LAN names with --allowed-host.

• Rate limit. 600 requests per minute per token by default (--rate-limit), answered with 429 and Retry-After.

Protocol support

Features used:

• tool annotations and titles;

• outputSchema with structuredContent;

• isError results with codes;

• resources, resource templates and completions;

• prompts;

• progress notifications, and cancellation that stops child processes;

• resources/list_changed;

• server instructions, kept under Claude Code's 4,096-character limit.

The jobs tool gives every client, whatever it supports, a way to poll long-running work.

Architecture

 MCP client ──stdio / Streamable HTTP──► MCPServer (SDK 2.3)
                                          │  auth middleware: token → caller (HTTP only)
                                          ▼
                     ┌──────────── catalog.py ────────────┐
                     │ core tools · search · call · batch │
                     │ jobs · resources · prompts         │
                     └──────────────┬─────────────────────┘
                                    ▼
             tools/*.py ── ToolBase._register: annotations, budget,
                                    tab handle, Result → structured + text,
                                    exception → {error, code, hint}
                                    ▼
             dom.py: isolated world, element ids, trusted input, CDP geometry
             session.py: browser, tabs and owners, logs, Fetch (proxy auth + interception)
                                    ▼
                         zendriver ──CDP──► headed Chrome

Development

uv sync --dev
uv run ruff check . && uv run ruff format --check .
uv run mypy src
uv run pytest                                   # unit, contract and protocol tests
DISPLAY=:99 ZENDRIVER_MCP_LIVE=1 uv run pytest tests/test_live.py   # real Chrome
uv run python scripts/gen_tool_docs.py          # regenerate docs/tools.md

The test suite enforces the conventions every tool must follow:

• every tool has a title, annotations, an output schema and described parameters;

• no tool returns an error as a success string;

• no selector is interpolated into page JavaScript;

• the default surface stays under a size budget;

• the instructions name only tools that exist and stay under the size limit.

CI runs all of this, plus the live test under Xvfb.

Acknowledgements

Built on zendriver and the MCP Python SDK. The tool set started from Zendriver-MCP by Shubham Choulkar; the MCP layer, element access, error model, HTTP security and test suite were rewritten for this project.

License

MIT