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.

Geizhals sits behind a Cloudflare JS challenge, so this drives a real (patched, headed) browser to reach the page. Search parsing is anchored on the live galleryview__* markup; product detail is read from the page's JSON-LD (ProductGroup → variant AggregateOffer), which carries the per-merchant offers directly. Both paths were verified end-to-end against live pages (July 2026).

Note on sorting: the default relevance sort returns the products you searched for. sort=price asks Geizhals for cheapest-first across its broad free-text match, which for loose queries surfaces cheap loosely-related items — prefer it only with a specific query.

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.

Related MCP server: ssc

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 — in practice it will not clear from a typical VPS. Route the browser through a residential IP by setting GH_PROXY to an HTTP proxy that egresses from one (for a self-hosted setup, a small proxy on a home box reachable over a VPN/tailnet works well):

docker run --rm -p 8000:8000 --shm-size=1g \
  -e GH_PROXY=http://192.168.1.10:8888 \
  ghcr.io/jnslmk/geizhals-mcp:latest

browser.py passes it straight to chromium.launch(proxy=…). From a residential IP no proxy is needed.

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.