geizhals-mcp

An MCP server that lets an LLM search Geizhals, a leading German/DACH price-comparison site, for the cheapest offers on new products. Built for self-hosting: one container, no API keys, no per-query credits.

Companion to jnslmk/kleinanzeigen-mcp — that one covers second-hand classifieds, this one covers new retail goods.

⚠️ Status: scaffolded, not yet smoke-tested. Geizhals sits behind a Cloudflare JS challenge, so this drives a real (patched, headed) browser to reach the page. The class-name-based selectors in scraper.py (_SEL) were written without live-HTML access and must be verified against real pages before the extraction can be trusted. The JSON-LD and product-href paths are designed to hold regardless. See Verifying the scraper.

Tools

The intended flow is search_products → pick interesting ids → get_products_batch. Search results omit the per-merchant offer tables so a broad search does not blow up the model's context window.

How it works

Geizhals has no public API and is fronted by Cloudflare's "Sichere Verbindung wird überprüft" JS challenge, which returns 403 to any plain HTTP client. So:

• Browser: patchright (a patched, undetected Playwright fork) drives Chromium headed under Xvfb — a headed browser behind a virtual display clears Cloudflare far more reliably than headless from a datacenter IP.

• Parsing: scraper.py prefers the page's application/ld+json Product block and the stable aNNNNNNN.html product hrefs, falling back to CSS selectors (collected in _SEL) for the human-readable fields.

Running it

docker run --rm -p 8000:8000 --shm-size=1g ghcr.io/jnslmk/geizhals-mcp:latest

Streamable HTTP at http://localhost:8000/mcp, plain GET /healthz for container healthchecks. Give the container at least 1.5 GB of memory and --shm-size=1g — Chromium maps its renderer heap into /dev/shm.

Configuration

LibreChat

mcpServers:
  geizhals:
    type: streamable-http
    url: "http://geizhals-mcp:8000/mcp"
    timeout: 180000
    chatMenu: true

mcpSettings:
  allowedAddresses:
    - "geizhals-mcp:8000"

allowedAddresses is required — LibreChat's SSRF guard blocks MCP URLs that resolve to private addresses, which a sibling container always does. The timeout is generous because a cold call starts a browser and waits out a Cloudflare challenge.

Claude Code

claude mcp add --transport http geizhals http://localhost:8000/mcp

Development

uv venv && uv pip install -e .
patchright install chromium
# Headless is fine for a quick check; headed (default) needs a display:
GH_HEADLESS=1 python -m geizhals_mcp

Verifying the scraper

The extraction was written without live-HTML access. Before trusting a release:

1. Run the server and call search_products with a common term (e.g. RTX 4070).

2. If results come back empty but the logs show no Cloudflare block, the row selectors in _SEL are stale — capture a real search page (page.content()), inspect it, and correct _SEL["row"], _SEL["row_price"] and _SEL["row_offercount"].

3. Do the same for get_product against _SEL["offer_*"].

4. If calls fail with a Cloudflare-timeout error, the datacenter IP is flagged — route egress through a residential/mobile proxy (see below).

Cloudflare and proxies

Cloudflare challenges are much harsher on datacenter IPs. If the headed-Xvfb browser cannot clear them from your host, point Chromium at a residential/mobile egress proxy. browser.py is the single place to add a proxy= argument to chromium.launch.

Images

ghcr.io/jnslmk/geizhals-mcp — multi-arch (linux/amd64, linux/arm64), built by GitHub Actions on native runners for each architecture.

Caveats

Geizhals has no public API, so this scrapes the site with a headless browser. It can break whenever Geizhals change their markup or tighten Cloudflare, and heavy or parallel use will trip bot detection — particularly from a datacenter IP. Scraping is also at odds with Geizhals' terms of service. Keep it to personal-scale use; the conservative concurrency defaults exist for exactly this reason.

License

MIT — see LICENSE.