dawg-mcp

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

🇷🇺 Built for Runet. DAWG is purpose-built for the Russian segment of the web: Russian residential proxies and geolocation (city slugs like moskva, spb, …) and stealth fingerprints tuned for RU sites. If your agent needs to browse or scrape Russian sites (Yandex, Ozon, Wildberries, Avito, gosuslugi, banks, …), this is the tool it was made for.

• 🌐 Remote stealth browser — provision an on-demand Chromium (RU proxy, geo, stealth 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

Install / run

# Recommended — straight from PyPI (fast: downloads a prebuilt wheel)
uvx dawg-mcp

# Or with pip
pip install dawg-mcp && dawg-mcp

# From GitHub (no PyPI), pinned to a tag:
uvx --from git+https://github.com/dawgswarm/dawg-mcp@v0.1.0 dawg-mcp

# Local checkout (development) — run from the repo root
uv run dawg-mcp

# As a module
python -m 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.

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": ["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 user --env DAWG_API_KEY=your_key -- uvx dawg-mcp

# local working tree:
claude mcp add dawg --scope user --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 = ["dawg-mcp"]

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

Configuration

Env var	Required	Default	Description
DAWG_API_KEY	yes	—	Your DAWG API key
DAWG_BASE_URL	no	https://dawgswarm.ru	Platform base URL
DAWG_PROVISION_TIMEOUT	no	120	Max seconds to wait for a browser to be ready
DAWG_POLL_INTERVAL	no	2	Seconds between readiness polls
DAWG_DEFAULT_NAV_TIMEOUT_MS	no	30000	Default navigation timeout
DAWG_DEFAULT_ACTION_TIMEOUT_MS	no	15000	Default action timeout
DAWG_SNAPSHOT_MAX_CHARS	no	60000	Truncate snapshot/content output
DAWG_MAX_SESSIONS	no	4	Max concurrent browsers
DAWG_LOG_LEVEL	no	INFO	Log level (logs go to stderr)

Tools

Browser — lifecycle

Tool	Description
browser_provision(proxy?, geo?)	Provision a remote stealth Chromium. geo = city slug ("moskva") or "lat,lon". Returns session_id + initial snapshot.
browser_release(session_id?)	Release a browser back to the pool.
browser_list_sessions()	List active sessions.

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.

Tool	Description
browser_navigate(url, timeout_ms?)	Go to a URL.
browser_navigate_back() / browser_navigate_forward()	History navigation.
browser_snapshot()	See the page — ARIA tree with [ref=eN] markers.
browser_click(element, ref, double?, button?)	Click an element by ref.
browser_type(element, ref, text, submit?, clear?)	Type into a field by ref.
browser_fill_form(fields)	Fill many fields at once ([{element, ref, value}]).
browser_select_option(element, ref, values)	Choose <select> option(s).
browser_hover(element, ref)	Hover an element.
browser_press_key(key)	Press a key ("Enter", "Control+a", …).
browser_wait_for(text?, text_gone?, time_ms?)	Wait for text / its disappearance / a delay.
browser_get_text(format?, selector?)	Get page text or HTML.
browser_take_screenshot(full_page?, ref?)	PNG image (visual verification only).
browser_evaluate(function, ref?)	Run JS, return JSON result.
browser_tabs(action, index?, url?)	list / new / select / close tabs.

Scraper

Tool	Description
scrape_page(url, format?, main_content?, include_links?, render?, timeout_ms?)	Scrape one URL → content.
scrape_crawl(url, max_depth?, max_pages?, …)	Start a crawl job → job_id.
scrape_batch(urls, concurrency?, …)	Start a batch job → job_id.
scrape_job_status(job_id, wait?, wait_timeout?)	Poll a crawl/batch job.
scrape_cancel_job(job_id)	Cancel a job.

Account

Tool	Description
account_usage()	Current usage and tariff plan.

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.