# GDD - AI-Controlled Browser Farm [Health: Active]

**Category:** 📂 Browser Automation  
**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

## Tools
Capabilities this server exposes over MCP:

- **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
- **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
- **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
- **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
- **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
- **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
- **gdd_quick_auth** — Auto-register and login with generated credentials
- **gdd_execute_js** — Execute JavaScript and return result
- **gdd_storage** — Read/write/clear localStorage/sessionStorage
- **gdd_cookies** — Read or clear browser cookies
- **gdd_get_manual** — Full GDD manual for AI self-learning
- **gdd_check_update** — Check for newer versions
- **gdd_update** — Download and install update (restarts GDD)

## Claude Desktop Quick Installation
No generated config for this server: it installs through its own setup steps.

The project's own setup steps (from https://github.com/Cap-of-tea/GDD), copied verbatim. Run them in order; they are not an mcpServers config.

1. Start the server:

```sh
bash Scripts/setup-macos.sh && ./GDD.Headless
```

2. Start the server:

```sh
docker run -p 9700:9700 ghcr.io/cap-of-tea/gdd
```

3. Install:

```sh
bash Scripts/install-deps.sh && ./GDD.Desktop
```

4. Start the server:

```sh
bash Scripts/setup-macos.sh && ./GDD.Desktop
```

5. Run:

```sh
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
```

6. Install:

```sh
docker build -t gdd .
```

## Documentation

## What GDD - AI-Controlled Browser Farm does

GDD - AI-Controlled Browser Farm MCP server exposes an HTTP MCP endpoint for operating multiple isolated Chromium instances. Each browser instance has its own profile, cookies, device settings, geolocation, and network conditions. Agents can create and remove browser instances, address each one by player ID, and inspect the current collection with its active state.

The server is suited to browser-based application testing and scripted interaction. An agent can open a site, complete forms, trigger touch or mouse interactions, capture screenshots, and inspect page output. Multiple browsers can be configured with different device presets so the same workflow can be checked across phones, tablets, and desktops.

## How it works

GDD starts a headless or headed browser-control service and listens on port 9700 by default. MCP clients connect to `http://localhost:9700/mcp`. The agent first creates one or more players, optionally selecting a device preset, then passes the relevant player ID to navigation, input, reading, and diagnostic tools.

Input actions use browser-level events. Tapping chooses touch or mouse input according to the emulated device, while typing sends trusted key events and supports contenteditable elements. Optional humanization adds cursor paths or per-key timing variation. Dragging uses real pointer events and can target coordinates or another element. Page state can be checked through text reads, screenshots, console output, network details, notifications, and the current URL or title.

## Setup and configuration

Download the server package for Windows, Linux, or macOS, or run the published Docker image. The server can also be installed for Claude Desktop through the provided `.mcpb` package. Linux, macOS, and Windows packages include platform-specific launch instructions; Chromium dependencies are included in the Docker image.

Start the binary directly, or add `--headless` for CI/CD environments. Other documented flags include `--stealth`, `--stealth-max`, `--update`, `--version`, and `--help`. Connect an MCP client with an HTTP server entry pointing to `http://localhost:9700/mcp`. Client configuration changes require restarting the client session.

GDD - AI-Controlled Browser Farm can alternatively be launched through the repository's Windows, Linux, or macOS stdio proxy scripts. The desktop edition is separate from the headless server and provides a browser-thumbnail grid for manually taking over sessions.

## Tools and capabilities

The listed tools cover:

- Creating, removing, listing, and inspecting browser instances.
- Navigating, reloading, going backward or forward, and waiting for CSS selectors.
- Tapping, swiping, dragging, scrolling, hovering, typing, pressing keys, selecting options, and handling JavaScript dialogs.
- Reading one or many matching elements and capturing JPEG screenshots.
- Applying device presets, viewport dimensions, location, timezone, locale, language, and network conditions.
- Reading console output, uncaught exceptions, network requests, request timing, status codes, and push notifications.
- Rewriting response headers to remove framing restrictions such as `X-Frame-Options` and CSP.

## Limitations and notes

The server uses port 9700, while the optional desktop application uses port 9800. By default, browsers launch in headed mode, so headless operation must be selected for display-free environments.

Claude Code asks for confirmation on each MCP tool call by default; its documented permission setting can allow the GDD tool namespace without repeated prompts. The material does not specify authentication or remote-access controls for the HTTP endpoint, so deployment beyond the local machine should be evaluated separately.

_Full upstream README: https://allmcps.com/mcp/gdd-ai-controlled-browser-farm/readme_