Groundhog

Safe, self-hosted web grounding for AI agents and crawlers. Groundhog is an MCP server that fetches live web pages through a real, stealth-patched Chrome (over CDP) and returns clean Markdown with provenance — without the SSRF holes of plain fetchers and without getting blocked like plain HTTP clients.

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

Quick start

Prerequisite: the stealth browser must be running. The MCP server is a thin client that drives Chrome over CDP, so start the browser first. If it isn't reachable, read_url returns a plain-language message on how to start it, and the status tool reports reachability. Set GROUNDHOG_AUTO_START_BROWSER=true to have Groundhog run docker compose up -d for you (requires Docker).

1. Start the stealth browser

docker compose up --build -d
curl -s http://localhost:9222/json/version    # CDP is live

2. Add it to your MCP client

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

{
  "mcpServers": {
    "groundhog": {
      "command": "uvx",
      "args": ["groundhog-mcp"],
      "env": { "CDP_URL": "http://127.0.0.1:9222" }
    }
  }
}

uvx fetches groundhog-mcp from PyPI on first run. To run from source instead: cd mcp && uv sync && uv run groundhog-mcp.

Tools

read_url(url, format="markdown", max_tokens=None, query=None, include_hidden=False)

Fetches a page and returns clean content plus provenance.

Because Groundhog renders a real DOM, it can evaluate computed styles. Text invisible to humans — display:none, visibility:hidden, opacity ≤ 0.05, font-size < 4 px, and zero-size elements — is stripped by default and each occurrence reported in threats with its signal type and a short excerpt. Pass include_hidden=True to keep the stripped text in the output; threats is still populated so you know it was there. Pass query to replace blunt head-truncation with relevance-ranked passage selection: content is chunked on markdown structure, ranked by lexical (BM25) relevance, and the top passages within the token budget are returned; matches gives each passage's heading, character offset, and score for downstream citation. Ranking runs on sanitized content, so hidden-text injection payloads cannot influence which passages surface.

status()

Reports whether Groundhog can reach the stealth browser. Returns browser_reachable

... View full README on GitHub