# tweakers-mcp

MCP server for [Tweakers Pricewatch](https://tweakers.net/pricewatch/): let Claude search products,
read full specifications, filter a category on specs, and find the cheapest shops (new items by
default, refurbished/open-box only when you ask for it).

Built on [tweakers-pricewatch](https://github.com/hatemosphere/tweakers-pricewatch) (unofficial,
reverse-engineered endpoints).

> "Find the best deal fridge with energy label A and under 30 dB, then the best price per litre."

## How to install

Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (`brew install uv`).

**Claude Code**

```
claude mcp add tweakers -- uvx --from git+https://github.com/rleroi/tweakers-mcp tweakers-mcp
```

**Claude Desktop**: add this to `~/Library/Application Support/Claude/claude_desktop_config.json`
(Windows: `%APPDATA%\Claude\claude_desktop_config.json`) and restart Claude Desktop. Desktop does not
use your shell PATH, so use the absolute path from `which uvx`:

```json
{
  "mcpServers": {
    "tweakers": {
      "command": "/absolute/path/to/uvx",
      "args": ["--from", "git+https://github.com/rleroi/tweakers-mcp", "tweakers-mcp"]
    }
  }
}
```

The first start takes a few seconds while uv builds the package.

## Tools

| Tool | What |
|---|---|
| `find_cheapest(query)` | Search, pick best hit with offers, return info + specs + cheapest offers |
| `search_products(query)` | Autocomplete search (~8 hits max) |
| `get_product(product_id)` | Product info + cheapest offers |
| `get_cheapest_offers(product_id)` | Offers sorted by total price (incl. shipping), with clickout URL |
| `get_specs(product_id)` | Spec table as `{group: {label: value}}` |
| `get_category_filters(slug, query)` | Spec filters of a category (select options, range bounds) |
| `browse_category(slug, filters, details)` | Category listing, filtered server-side on specs; `details=N` adds specs + offers for the first N |
| `list_categories()` | Category slugs |

Refurbished / open-box / outlet offers are excluded by default (`refurbished_hidden` shows how many);
pass `include_refurbished=true` only when explicitly asked for. The package ignores the offer
condition, so offers are parsed here.

Filter first, then fetch details: `browse_category('koelkasten', filters={'Energieklasse (2021)': ['A'],
'Geluidssterkte (max.)': {'max': 29}}, details=25)` is ~20s instead of scanning hundreds of products.

Specs are parsed here from the product page (the package has none). Requests are
throttled (0.5s) and specs are cached per process.

## Development

```
git clone https://github.com/rleroi/tweakers-mcp && cd tweakers-mcp
uv sync
uv run tweakers-mcp        # stdio server
```

## Caveats

- Unofficial: relies on reverse-engineered Tweakers endpoints and HTML, which can change or be
  blocked at any time. Check Tweakers' terms before heavy use.
- Search is the autocomplete endpoint (~8 hits). Use `browse_category` with filters for more.
- Some products lack specs on Tweakers (e.g. no dB value), so a spec filter silently skips them.
- Not affiliated with Tweakers. MIT licensed.