# geizhals-mcp

A small [MCP](https://modelcontextprotocol.io) server that lets an assistant
search [geizhals.de](https://geizhals.de) and look up shop prices for a product.
I built it to stop tabbing back and forth to the browser while comparing
hardware prices.

It exposes two tools:

- `search_products(query, limit=15)` – full-text product search; returns the
  lowest price, number of offers and the product URL for each hit.
- `get_product(product)` – takes a product URL or id and lists the individual
  shop offers (cheapest first) with the price range.

## Install

```sh
git clone https://github.com/spinnerich/geizhals-mcp
cd geizhals-mcp
uv sync          # or: pip install -e .
```

## Wiring it into a client

For Claude Code, one command does it (point it at wherever you cloned the repo):

```sh
claude mcp add geizhals -- uv --directory /path/to/geizhals-mcp run geizhals-mcp
```

Add `--scope user` to make it available in every project, or `-e KEY=value` to
set any of the variables below. `claude mcp list` shows it's registered.

For Claude Desktop, add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "geizhals": {
      "command": "uv",
      "args": ["run", "geizhals-mcp"]
    }
  }
}
```

Or run it directly to test: `uv run geizhals-mcp`.

## Configuration

A few environment variables, all optional:

| Variable | Default | Purpose |
| --- | --- | --- |
| `GEIZHALS_DOMAIN` | `geizhals.de` | Use `geizhals.at` or `geizhals.eu` for other regions. |
| `GEIZHALS_MIN_DELAY` | `1.0` | Minimum seconds between requests. |
| `GEIZHALS_IMPERSONATE` | `chrome` | curl_cffi browser profile used for the TLS handshake. |

## Caveats

Geizhals has no public API, so this reads the normal website. The site is
behind Cloudflare, which is why the requests go through `curl_cffi` with a
browser TLS fingerprint – a plain HTTP client just gets a 403. Because there's
no API the parsing is tied to the current page layout and may need a nudge when
they change things.

Keep the request rate sane (the default delay is there for a reason) and use
this for your own price checks, not for hammering their servers.