Groundhog

Web search, read and research for AI agents — through a real, stealth-patched Chrome. Groundhog is an MCP server that finds pages, reads them, and researches across them, returning clean Markdown a model can trust: text no human could see is stripped by default before the model reads it, every source comes back with a provenance receipt, and a real browser reads pages that block plain fetchers — without the SSRF holes of naive fetch tools.

agent / crawler  ──MCP──▶  Groundhog (search, read_url, research)  ──CDP──▶  stealth Chrome  ──▶  the web

Quick start

Add Groundhog to your MCP client — that's it. On the first fetch, Groundhog pulls and starts the stealth-browser container for you (Docker or Podman required); no repo checkout, no manual steps. When the default (non-compose) auto-start path has to run, any stale container named groundhog-browser is removed first; a reachable browser is never touched.

Claude Code:

claude mcp add groundhog -- uvx groundhog-mcp

Claude Desktop / Cursor / Windsurf (claude_desktop_config.json or equivalent):

{
  "mcpServers": {
    "groundhog": {
      "command": "uvx",
      "args": ["groundhog-mcp"]
    }
  }
}

uvx fetches groundhog-mcp from PyPI on first run. The first fetch pulls the browser image (once, a few minutes); later fetches are instant. No container runtime? The status tool and any error say how to install one — or point CDP_URL at a hosted browser for zero-install use.

Prefer to manage the browser yourself? Start it and Groundhog will just use it:

docker run -d --rm --name groundhog-browser --shm-size 512m \
  -p 127.0.0.1:9222:9222 -- ghcr.io/dmytrome/groundhog:latest
# or, from a repo checkout: docker compose up --build -d
curl -s http://localhost:9222/json/version    # CDP is live

Set GROUNDHOG_AUTO_START_BROWSER=false to disable auto-start. To run the MCP server from source: cd mcp && uv sync && uv run groundhog-mcp.

All four tools are annotated readOnlyHint, which is what lets a client run them without a per-call confirmation. That describes what they do to your data: nothing is written, and no remote state is changed. Worth knowing, because it is the one exception: with auto-start on, the first call may pull and run the browser container, and remove an unreachable container named groundhog-browser first. A reachable one is never touched, and GROUNDHOG_AUTO_START_BROWSER=false turns the whole path off.

What makes it different

• Hidden text is stripped before the model reads it. Groundhog renders a real DOM, so it can judge what a human would actually see and strip what they could not, reporting each occurrence in threats. A strong heuristic, not a proof — see the limits of hidden-text detection. The eleven signals, the threats caveat and the include_hidden exception are documented under read_url.
• Every source carries a receipt. SHA-256 hash of the extracted content, canonical URL, language, word count, and author/date when the page declares them — so a downstream claim traces back to exactly what was read. read_url returns the fetch time alongside it as fetched_at.
• Safe by default. The SSRF guard resolves each host before navigating and refuses to return content from a URL that redirects into a private address. Read-only, with per-domain rate limiting. This matters most in research, where a third party chooses the URLs. See Security for the full blocklist and the guard's limits.
• No automation tell. Puppeteer/Playwright/

... View full README on GitHub