# GDD - AI-Controlled Browser Farm [Health: Active] **Category:** πŸ’» Developer Tools **Repository:** https://github.com/Cap-of-tea/GDD **GitHub Stars:** 12 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/gdd-ai-controlled-browser-farm ## Description AI-controlled browser farm: N isolated Chromium instances with 36 MCP tools ## Claude Desktop Quick Installation Heuristic fallback β€” verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "gdd-ai-controlled-browser-farm": { "command": "npx", "args": ["-y","gdd-ai-controlled-browser-farm"] } } ``` ## Documentation & README

GDD

GDD β€” Giggly-Dazzling-Duckling

AI-controlled browser farm on your machine
Simulate multiple real users across 22 device types β€” test your site like it's launch day.

Release Platforms MCP MCP Registry License

Claude Code Cursor

--- ## How It Works > **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. ```text 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 ``` 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`.

GDD Video Wall β€” 3 devices testing simultaneously

--- ## 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. **Server (headless)** β€” the MCP backend: | Platform | Download | Run | |----------|----------|-----| | **Linux** | [GDD-Server-Linux.tar.gz](https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Server-Linux.tar.gz) | `chmod +x GDD.Headless && ./GDD.Headless` | | **macOS ARM** | [GDD-Server-macOS-ARM.tar.gz](https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Server-macOS-ARM.tar.gz) | `bash Scripts/setup-macos.sh && ./GDD.Headless` | | **macOS Intel** | [GDD-Server-macOS-Intel.tar.gz](https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Server-macOS-Intel.tar.gz) | `bash Scripts/setup-macos.sh && ./GDD.Headless` | | **Windows** | [GDD-Server-Windows.zip](https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Server-Windows.zip) | `.\GDD.Headless.exe` | | **Docker** | `ghcr.io/cap-of-tea/gdd` | `docker run -p 9700:9700 ghcr.io/cap-of-tea/gdd` | | **Claude Desktop** | [Win](https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Server-Windows.mcpb) / [Mac ARM](https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Server-macOS-ARM.mcpb) / [Mac Intel](https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Server-macOS-Intel.mcpb) (.mcpb) | Open `.mcpb` file β€” installs as desktop extension | **Desktop app (GUI)** β€” a live grid of browser thumbnails you can click into: | Platform | Download | Run | |----------|----------|-----| | **Windows** | [GDD-Desktop-Windows.zip](https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Desktop-Windows.zip) | Extract, run `GDD.exe` ([WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) required) | | **Linux** | [GDD-Desktop-Linux.tar.gz](https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Desktop-Linux.tar.gz) | `bash Scripts/install-deps.sh && ./GDD.Desktop` | | **macOS ARM** | [GDD-Desktop-macOS-ARM.tar.gz](https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Desktop-macOS-ARM.tar.gz) | `bash Scripts/setup-macos.sh && ./GDD.Desktop` | | **macOS Intel** | [GDD-Desktop-macOS-Intel.tar.gz](https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Desktop-macOS-Intel.tar.gz) | `bash Scripts/setup-macos.sh && ./GDD.Desktop` | 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. **One-liner (Linux):** ```bash curl -sL https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Server-Linux.tar.gz | tar xz && chmod +x GDD.Headless && ./GDD.Headless ```
Docker ```bash # 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. --- ## Connect to Your AI Client Add to `.mcp.json` and restart your AI client: ```json { "mcpServers": { "gdd": { "url": "http://localhost:9700/mcp" } } } ``` That's it. Start GDD, tell Claude or Cursor to test your app. > **Claude Desktop users:** Download the `.mcpb` file from [Releases](https://github.com/Cap-of-tea/GDD/releases/latest) and open it β€” GDD installs as a one-click desktop extension. No manual config needed.
Config file locations | Client | Project config | Global config | | ------ | -------------- | ------------- | | Claude Code | `/.mcp.json` | `~/.claude/.mcp.json` | | Cursor | `/.cursor/mcp.json` | `~/.cursor/mcp.json` | | VS Code / Windsurf / Antigravity | `/.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 (Windsurf, Antigravity, Copilot) VS Code-based IDEs use a different config format than Claude Code / Cursor. **Project config** β€” `.vscode/mcp.json`: ```json { "servers": { "gdd": { "type": "http", "url": "http://localhost:9700/mcp" } } } ``` **Global config** β€” open via `Cmd+Shift+P` β†’ "Open User Settings (JSON)": ```json { "mcp": { "servers": { "gdd": { "type": "http", "url": "http://localhost:9700/mcp" } } } } ``` Global `settings.json` location: macOS β€” `~/Library/Application Support//User/settings.json`, Linux β€” `~/.config//User/settings.json`, Windows β€” `%APPDATA%//User/settings.json`. Replace `` with your editor name (Code, Windsurf, Antigravity, etc.). **stdio-proxy** alternative (`.vscode/mcp.json`): ```json { "servers": { "gdd": { "type": "stdio", "command": "bash", "args": ["/absolute/path/to/Scripts/mcp-proxy.sh"] } } } ```
Permissions (Claude Code) By default, Claude Code asks for confirmation on every MCP tool call. To allow GDD tools without prompts, add to `~/.claude/settings.json`: ```json { "permissions": { "allow": [ "mcp__gdd__*" ] } } ``` This single wildcard covers all 39 GDD tools. Restart Claude Code after editing.
Auto-launch via stdio proxy (alternative) Proxy scripts start GDD automatically when your AI client connects: **Windows:** ```json { "mcpServers": { "gdd": { "command": "powershell", "args": ["-ExecutionPolicy", "Bypass", "-File", "C:/path/to/Scripts/mcp-proxy.ps1"] } } } ``` **Linux / macOS:** ```json { "mcpServers": { "gdd": { "command": "bash", "args": ["/path/to/Scripts/mcp-proxy.sh"] } } } ``` Add `"--headless"` to the `args` array for CI/CD. > **Tip:** On first launch, GDD downloads Chromium (~80 MB). If your AI client times out, run GDD manually first, then reconnect.
Autostart as service (macOS / Linux) **macOS (launchd):** ```bash bash Scripts/install-launchd.sh # headed (default) bash Scripts/install-launchd.sh --headless # for CI/CD ``` Manage: `launchctl list | grep gdd` / `bash Scripts/install-launchd.sh --uninstall` **Linux (systemd):** ```bash mkdir -p ~/.config/systemd/user cat > ~/.config/systemd/user/gdd.service << 'EOF' [Unit] Description=GDD Multi-Browser Testing Server [Service] ExecStart=/path/to/GDD.Headless WorkingDirectory=/path/to/gdd-directory Restart=on-failure [Install] WantedBy=default.target EOF systemctl --user daemon-reload systemctl --user enable --now gdd ```
Direct HTTP (without AI client) ```bash 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 - **Diagnostics** β€” Console errors, network traffic, performance metrics, push notifications - **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](https://registry.modelcontextprotocol.io) - **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 `