Groundhog MCP server

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

Measured against other fetch layers

Twenty-eight pages, each carrying text a human reader cannot see, plus three controls carrying none. A case passes when the payload does not reach the model and the article text still does — a fetcher that returns nothing contains every payload and is useless.

Groundhog reports 25 of the 28 rather than all of them. The other three — a hidden input value, a meta description, an iframe srcdoc — are contained because no extractor ever collected them, and naming text that was never on its way to the model would describe work nothing did.

Containment happens by accident all the time — an article extractor prunes a hidden because its heuristics dislike it, not because anything asked whether a reader could see it. That is why the last column matters: nothing else tested tells the caller that anything was removed, so an empty threat list and a page with nothing hidden look identical.

The corpus is published at dmytrome.github.io/groundhog, so any fetcher can be measured against the same pages. Harness, per-case results and the limits of what this proves are in benchmark/ — including that hosted services are a snapshot of the date recorded in RESULTS.md.

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 (claudedesktopconfig.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

Shortened. The full README is on GitHub.