dawg-mcp

An MCP server that gives AI agents (Claude Code, Codex, …) direct access to the DAWG platform:

• 🌐 Remote stealth browser — provision an on-demand Chromium (proxy, geo, anti-bot, captcha solving baked in) and drive it with snapshot/click/type/screenshot tools.

• 🔎 Web scraping — single-page scrape plus crawl/batch jobs returning clean markdown/text/html.

• 📊 Account usage — read the current plan, limits and consumption for your API key.

The browser tools mirror the interaction model of the official @playwright/mcp: the agent takes an accessibility snapshot of the page (an ARIA tree with [ref=eN] markers), then targets elements by ref. This is far more reliable and token-efficient than screenshot-and-guess.

Browsers run on DAWG infrastructure — no local browser is launched or downloaded; the server only attaches to the remote Chromium over CDP.

Requirements

• Python ≥ 3.10

• A DAWG API key (X-API-Key) from https://dawgswarm.ru

• uv (recommended) for uvx/uv run

Related MCP server: Navvi

Install / run

# Run straight from GitHub (recommended — no PyPI needed)
uvx --from git+https://github.com/dawgswarm/dawg-mcp@main dawg-mcp

# Pin to a released tag for reproducibility:
uvx --from git+https://github.com/dawgswarm/dawg-mcp@v0.1.0 dawg-mcp

# From a local checkout (development) — run from the repo root
uv run dawg-mcp

# As a module
python -m dawg_mcp

# If/when published to PyPI:
uvx dawg-mcp

DAWG_API_KEY must be set in the environment. No playwright install is needed — the server connects to a remote browser and never launches Chromium locally.

Distribution: this package is installed straight from GitHub via uvx --from git+…. uv clones + builds it on first run and caches it, so the experience is one command, like PyPI — just a slightly longer config line and a one-time build on first launch. Pin to a tag (@v0.1.0) for reproducibility. PyPI publishing is optional and not required.

Private repo? uvx --from git+https://… needs non-interactive git auth. Either use SSH (git+ssh://git@github.com/dawgswarm/dawg-mcp@main) with an ssh-agent, or install once with uv tool install git+ssh://… and set "command": "dawg-mcp" in your MCP config.

Register with an agent

Claude Code

Project scope — commit .mcp.json (it reads ${DAWG_API_KEY} from your shell):

{
  "mcpServers": {
    "dawg": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/dawgswarm/dawg-mcp@main", "dawg-mcp"],
      "env": {
        "DAWG_API_KEY": "${DAWG_API_KEY}",
        "DAWG_BASE_URL": "${DAWG_BASE_URL:-https://dawgswarm.ru}"
      }
    }
  }
}

Or via the CLI:

claude mcp add dawg --scope project --env DAWG_API_KEY=your_key \
  -- uvx --from git+https://github.com/dawgswarm/dawg-mcp@main dawg-mcp

# local working tree:
claude mcp add dawg --scope project --env DAWG_API_KEY=your_key \
  -- uv run --directory /path/to/dawg-mcp dawg-mcp

Codex

Add to ~/.codex/config.toml (see examples/codex_config.toml):

[mcp_servers.dawg]
command = "uvx"
args = ["--from", "git+https://github.com/dawgswarm/dawg-mcp@main", "dawg-mcp"]

[mcp_servers.dawg.env]
DAWG_API_KEY = "your_key"
DAWG_BASE_URL = "https://dawgswarm.ru"

Configuration

Tools

Browser — lifecycle

Browser — driving

All take an optional session_id (defaults to the sole active session) and return a fresh AI snapshot after acting. Target elements by ref from the latest browser_snapshot.

Scraper

Account

Typical agent flow

browser_provision()                         → session_id + snapshot
browser_navigate(url="https://...")          → snapshot with [ref=eN] markers
browser_click(element="Login", ref="e12")    → fresh snapshot
browser_type(element="Email", ref="e8", text="...", submit=true)
browser_take_screenshot()                    → PNG to confirm visually
browser_release()

If a ref is stale (the page changed), the tool returns an error with a fresh snapshot appended so the agent can re-select.

Development

uv venv && uv pip install -e ".[dev]"
uv run pytest            # 21 unit/integration tests (no network)
uv run ruff check .

# Live end-to-end smoke test (needs a real key):
DAWG_API_KEY=... uv run python examples/smoke_test.py

# Inspect over stdio with the MCP Inspector:
DAWG_API_KEY=... npx @modelcontextprotocol/inspector uv run dawg-mcp

License

MIT — see LICENSE.