You: Open 3 iPhones and a desktop, navigate to myapp.com, test the signup form on all devices
Claude Code creates 4 browsers with device emulation, navigates each to your app, fills in the form, takes screenshots, checks console for errors — all in parallel.
gdd_add_players(3, device="iPhone 15 Pro") → players [1, 2, 3]
gdd_add_players(1, device="Desktop 1080p") → player [4]
gdd_navigate(1, "https://myapp.com") → all 4 browsers open your app
gdd_tap(1, "#signup-btn") → taps signup on iPhone
gdd_screenshot(1) → captures the result
gdd_get_console(1, level="error") → checks for JS errors
AI-controlled browser farm: N isolated Chromium instances with 36 MCP tools
2026-11-09
스타
—
도구
—
가동 시간
—
GDD runs N isolated Chromium instances, each with its own profile, cookies, device emulation, geolocation, and network conditions. It exposes 39 MCP tools via HTTP on localhost:9700.
Install
GDD comes in two flavours. The Server is headless — it's just the MCP backend, runs anywhere (including boxes with no display), and is all you need for pure AI automation. The Desktop app adds a GUI: a live grid of browser thumbnails you can click into to take over a session by hand. The Server runs on port 9700, the Desktop app on 9800 — so you can run both side by side.
The Windows app uses WebView2; the Linux/macOS app (built with Avalonia) drives real Chromium windows parked off-screen. Self-contained binary, ~70 MB. No .NET installation needed. Chromium downloads automatically on first launch.
# Run (headless, port 9700)
docker run -p 9700:9700 ghcr.io/cap-of-tea/gdd
# Or build locally
docker build -t gdd .
docker run -p 9700:9700 gdd
The Docker image runs in headless mode with all Chromium dependencies pre-installed.
By default, browsers launch in headed mode (visible windows). Add --headless for CI/CD. Other flags: --stealth and --stealth-max for anti-bot masking, --update to self-update, --version and --help. The Configuration section below lists every flag and environment variable.
That's it. Start GDD, tell Claude or Cursor to test your app.
Claude Desktop users: Download the .mcpb file from Releases and open it — GDD installs as a one-click desktop extension. No manual config needed.
Client
Project config
Global config
Claude Code
<project>/.mcp.json
~/.claude/.mcp.json
Cursor
<project>/.cursor/mcp.json
~/.cursor/mcp.json
VS Code / Windsurf / Antigravity
<project>/.vscode/mcp.json
IDE settings.json
Global and project configs are merged — servers from both are available simultaneously. Changes are picked up only when restarting the AI client session.
VS Code-based IDEs use a different config format than Claude Code / Cursor.
Global settings.json location: macOS — ~/Library/Application Support/<IDE>/User/settings.json, Linux — ~/.config/<IDE>/User/settings.json, Windows — %APPDATA%/<IDE>/User/settings.json. Replace <IDE> with your editor name (Code, Windsurf, Antigravity, etc.).
curl -X POST http://localhost:9700/mcp -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"gdd_add_players","arguments":{"count":1}}}'
GDD uses standard JSON-RPC 2.0 — works with curl, Python, Node.js, or any HTTP client.
Features
Multi-device — Run N isolated Chromium instances with 22 device presets (phones, tablets, desktops)
AI-native — 39 MCP tools for Claude Code, Cursor, or any MCP-compatible client
Cross-platform — Native GUI with a live video wall on Windows, Linux & macOS, plus a headless server for CI/CD
Full interaction — Navigate, tap, type, press keys and shortcuts, drag, swipe, scroll, hover, handle dialogs, take screenshots
Real keyboard — Typing sends genuine, trusted keystrokes (the full keydown→input chain), so input masks, autocomplete and maxlength behave exactly as they do for a real user, and rich-text (contenteditable) editors work; gdd_press handles single keys and shortcuts like Enter, Tab, Escape and Ctrl+A
Physical keyboard layouts — Keystrokes carry the real code/keyCode of the emulated locale's keyboard: Russian ЙЦУКЕН puts «а» on the physical KeyF, French AZERTY and German QWERTZ remap their keys, dead-key accents and AltGr symbols work. The layout follows gdd_set_language automatically (US, RU, DE, FR)
Human-like input — humanize=true drives a continuous cursor path (cubic Bézier with easing and micro-jitter) that carries over between clicks, hovers and drags; taps fire a single device-appropriate input (touch or mouse), never both
Anti-bot stealth — opt-in --stealth masks the usual automation tells (navigator.webdriver, etc.); --stealth-max adds headless/datacenter evasions (coherent user-agent client hints, a plausible WebGL vendor, realistic device metrics) — on a headless container this halved CreepJS's headless score
Proxy support — Route every browser through an upstream proxy with GDD_PROXY (with optional auth)
Header rewriting — gdd_set_headers can strip X-Frame-Options/CSP frame-ancestors to load a site in an iframe, or add/replace response headers
Device emulation — Screen size, DPR, touch, user agent, geolocation, timezone, language
Network control — Simulate 4G, Fast 3G, Slow 3G, or offline per browser
Error beacon — Every tool response warns about JS errors across all browsers automatically
Docker-ready — Official image on GHCR (ghcr.io/cap-of-tea/gdd), listed on the MCP Registry
Self-updating — Built-in version check and one-command update
MCP Tools (39)
Player Management
Tool
Description
gdd_add_players
Add N browser instances with optional device preset
gdd_remove_player
Remove a browser instance by player ID
gdd_list_windows
List all active browsers with current state
Navigation
Tool
Description
gdd_navigate
Navigate to a URL
gdd_wait
Wait for a CSS selector to appear (with timeout)
gdd_reload
Reload page (hard=true bypasses cache)
gdd_back
Navigate back
gdd_forward
Navigate forward
Interaction
Tool
Description
gdd_tap
Tap element by CSS selector or coordinates; sends a single device-appropriate input (touch on touch devices, mouse on desktop), never both. humanize=true adds a continuous human-like cursor path
gdd_swipe
Swipe gesture (up/down/left/right)
gdd_drag
Drag an element to (x, y) or onto another element via real pointer events (drives dnd-kit & HTML5 drag-and-drop)
gdd_scroll
Scroll page or element
gdd_type
Type text with real, trusted keystrokes (CDP dispatchKeyEvent — masks, autocomplete and maxlength behave as for a real user; works on contenteditable). Physical key codes follow the emulated layout (US/RU/DE/FR); humanize=true adds per-key jitter; paste=true inserts in one shot
gdd_press
Press a single key or shortcut (Enter, Tab, Escape, Arrow keys, F1–F12, or a character) with optional modifiers (Control/Alt/Shift/Meta); character keys follow the emulated layout
gdd_hover
Hover over element. humanize=true adds a continuous human-like cursor path
gdd_select
Select option from <select> dropdown
gdd_dialog
Handle JS alert/confirm/prompt dialogs
Reading & Screenshots
Tool
Description
gdd_read
Read text content of an element
gdd_read_all
Read text from all matching elements
gdd_screenshot
Capture JPEG screenshot at CSS pixel resolution
Emulation
Tool
Description
gdd_set_device
Set device preset (22 devices: phones, tablets, desktops)
gdd_set_viewport
Set custom viewport dimensions
gdd_set_location
Set geolocation, timezone, and locale
gdd_set_network
Set network conditions (4G, 3G, offline)
gdd_set_language
Set browser language
gdd_set_headers
Rewrite response headers — strip X-Frame-Options/CSP to allow framing
State & Diagnostics
Tool
Description
gdd_get_state
Browser state: URL, title, device, auth status
gdd_get_console
Console output and uncaught exceptions
gdd_get_network
Network requests with timing and status
gdd_get_notifications
Received push notifications
gdd_get_performance
Performance metrics (JS heap, DOM nodes, FPS)
gdd_clear_logs
Clear console and/or network logs
Auth & Execution
Tool
Description
gdd_quick_auth
Auto-register and login with generated credentials
GDD ships as three apps over one shared core. The two GUIs differ only in the desktop toolkit (WebView2 on Windows, Avalonia on Linux/macOS); all three expose the same 39 MCP tools.
Opt-in anti-bot masking — launches Chromium with AutomationControlled disabled and hides the usual automation tells (navigator.webdriver, etc.). Playwright engines (GDD.Desktop, GDD Server) only
false
Command-line flags
Flag
Description
--headed
Visible browser windows (default)
--headless
No UI — for CI/CD
--stealth
Enable anti-bot masking (same as GDD_STEALTH=true)
--stealth-max
Full stealth — client-hints UA metadata, WebGL/device/timezone spoofing; implies --stealth (same as GDD_STEALTH_MAX=true)
--update
Check for a newer version and install it if available
--version
Print the version and exit
--help
Show usage and exit
Environment variables
Handy for Docker and CI, where an appsettings.json file is awkward:
Variable
Description
GDD_STEALTH
true/1 to enable anti-bot masking (same as --stealth)
GDD_STEALTH_MAX
true/1 for full stealth (same as --stealth-max)
GDD_PROXY
Upstream proxy for every browser, e.g. http://host:3128 or socks5://host:1080 (Server / Playwright engines)
GDD_PROXY_USER / GDD_PROXY_PASS
Credentials for an authenticated proxy
GDD_CHROME_CHANNEL
Launch an installed Chrome build (e.g. chrome, chrome-beta) instead of bundled Chromium
GDD_PLAYER_IDLE_TIMEOUT_MINUTES
Headless server only. Auto-remove a player untouched for this many minutes, reclaiming its browser. Default 30; set 0 to disable. Prevents memory piling up when remote clients disconnect without removing their players
GDD runs entirely on your local machine. No telemetry, no analytics, no data collection.
No data leaves your machine — all browser profiles, screenshots, logs, and cookies stay in local storage
Browser profiles — stored in %LOCALAPPDATA%\GDD\Profiles (Windows) or ~/.local/share/GDD/Profiles (Linux/macOS)
No third-party services — GDD does not contact any external APIs except GitHub Releases for optional update checks
Update checks — gdd_check_update makes a single read-only request to api.github.com. Opt out by not calling the tool, or set CheckForUpdates: false in appsettings.json
MCP server — listens on localhost only (default port 9700), never exposed to the network