chrome-driverless

中文文档

A persistent, headed Chrome driven by Playwright, exposed through an MCP-style HTTP API (POST /mcp) with a built-in web console. Humans and AI agents share one long-lived browser: log in once through the console, then drive it via HTTP, CDP, Node.js scripts — or let an LLM complete tasks for you.

Highlights

• Persistent context — login state survives restarts in data/profiles/<name>/auth.json (exportable for reuse)

• MCP-style HTTP API — navigate, screenshot, click, type, keys, hover, evaluate, tabs, profiles, proxy toggle, raw mouse / scroll control

• Web console — layered live viewport (screenshot / element-highlight / virtual-cursor layers), touchpad-style pointer control, element picker, built-in DevTools

• Human mode — a bare Chromium with zero Playwright/CDP attachment, purpose-built for Cloudflare / Turnstile challenge pages (open the challenge, wait 5–15 s, it passes)

• Fingerprint profiles — real / Chrome·Win / Chrome·Mac / Safari·Mac, each self-consistent across HTTP User-Agent, JS platform/vendor/userAgentData, and sec-ch-ua headers

• Stealth audit — the classic 0–7 anti-detection checklist made runnable in one call (pw/stealth_audit, human/stealth_audit)

• Humanized input — mouse trajectories and keystroke cadence with reproducible seeds (HUMANIZE_SEED)

• Clipboard interop — Ctrl+C / Ctrl+V bridged between your machine and the remote page (paste = one-shot insertText, copy reads the remote selection)

• Network consistency — browser timezone aligned with the proxy's egress timezone; UA / sec-ch-ua coherence

• Real Google Chrome engine — set BROWSER_ENGINE=chrome for native brands + Widevine (fixes the two biggest Chromium-for-Testing fingerprint tells)

• GPU passthrough — WebGL renderer probing; real GPU by default when available (no SwiftShader software-rendering tell)

• Audio streaming — hear the browser at /audio.mp3 (PulseAudio null-sink → parec → ffmpeg)

• AI tasks — a browser-use-style agent: the DOM is distilled into numbered interactive elements ([3] <button>Sign in</button>), the LLM answers with index-based actions and self-corrects from execution feedback; any OpenAI-compatible endpoint works (DeepSeek preset), and a vision mode attaches screenshots for multimodal models

• Env-driven auto login — pw/auto_login fills login forms from BROWSER_LOGIN_* env vars, no credentials in code

• Node.js job scripts — pw/run_script executes scripts that connectOverCDP into the same browser, sharing login state

• Modular codebase — main.py + cd_*.py modules, each ≤600 lines

Related MCP server: browser-control-mcp-server

Quick start

pip install -r requirements.txt
python main.py        # serves 0.0.0.0:9223

Or with Docker (images built by GitHub Actions):

docker run -d --name chrome-driverless \
  -p 9223:9223 \
  -v chrome-data:/app/data \
  ghcr.io/friddle/chrome-driverless:latest

# real Google Chrome engine instead of Chromium-for-Testing:
docker run -d -p 9223:9223 -v chrome-data:/app/data \
  -e BROWSER_ENGINE=chrome \
  ghcr.io/friddle/chrome-driverless:latest

Open http://localhost:9223/ for the console.

Environment variables

Proxies are intentionally empty by default — inject them via env vars instead of hardcoding addresses.

HTTP endpoints

• GET / — web console

• GET /health

• POST /mcp — MCP method call: {"method": "pw/...", "params": {...}}

• GET /debug/status · /debug/logs · /debug/files · /debug/url

• GET /audio.mp3 — live browser audio stream

• GET /devtools/targets, GET /devtools/{rest} (+ WS bridges) — Chrome DevTools

MCP methods

Multi-tab concurrency & per-tab lock

One profile supports operating multiple tabs at the same time. Convention:

1. pw/new_tab {tab: "my-task", url: ...} creates (or reuses) a named tab; the response carries the tab name;

2. Any later pw/* call with {tab: "my-task"} runs on that tab (resolved by name; unknown names fail with tab not found);

3. Lock granularity is per tab: requests on the same tab are serialized — the next request starts only after the previous one finishes (locked automatically before execution); different tabs run concurrently;

4. Calls without tab take the global lock (single-browser serial semantics unchanged); ai/cancel bypasses locks so long tasks can always be interrupted;

5. /debug/status exposes tab_busy showing which named tabs currently have a task running.

Module map

Embedding into your app

1. Run the service (docker or bare) and expose port 9223.

2. Open the console URL in an in-app tab / iframe.

3. Log in to target sites in the console — state persists in auth.json for later scripts / CDP connections.

The service itself has no built-in auth — it is meant as an internal / embedded tool. Put an authenticating reverse proxy in front if you need access control.

Disclaimer

For personal learning and self-hosted automation only. Respect the terms of service of the websites you visit.