kleinanzeigen-mcp

willmehr

MCP servers for hunting deals on the German-speaking classifieds sites. TypeScript, over stdio locally or Streamable HTTP self-hosted; works with Claude Code, Claude Desktop, or any other MCP client.

Two servers ship from this repo, each registered separately:

They publish as two npm packages, willmehr and kleinanzeigen-mcp, released together from this repo at the same version.

The willhaben server was built by reverse-engineering the willhaben web app's own JSON API from a HAR capture. The Kleinanzeigen server is a port of jnslmk/kleinanzeigen-mcp — see Kleinanzeigen below.

Quick start

claude mcp add willmehr -- npx -y willmehr

claude mcp add kleinanzeigen -- npx -y kleinanzeigen-mcp

Or from a clone, which is what you want for hacking on it or self-hosting:

git clone https://github.com/taneron/willmehr.git && cd willmehr

npm install && npm run build

claude mcp add willmehr -- node "$PWD/dist/index.js" claude mcp add kleinanzeigen -- node "$PWD/dist/kleinanzeigen/index.js"

Either way you get both servers locally, in full mode. Both are listed in the official MCP registry, as io.github.taneron/willmehr and io.github.taneron/kleinanzeigen, so a client that reads the registry can find them without this README. The willhaben account tools need a session cookie of your own — see Authentication; everything else works anonymously and needs no setup.

To run it as a shared HTTP server instead, on your own box, see Hosting. Nothing in this project phones home to anyone else's instance.

Modes

Both servers run in one of two modes. Same code, same binary — the mode is chosen at startup with --public / --full or WILLMEHR_MODE, and defaults to full.

public is what makes this safe to host for other people: the process holds no credential, and registers no tool that could use one, so a shared deployment cannot leak a session it never loads. The tighter pacing is the other half — in public mode every user shares one outbound IP, and both sites rate-limit per IP.

node dist/index.js --public               # willhaben, anonymous

WILLMEHR_MODE=public node dist/kleinanzeigen/index.js

Account tools deliberately have no hosted equivalent. willhaben authenticates through Keycloak with PKCE, so there is no scoped token a third party could be granted — the only thing a hosted server could ask for is the raw session cookie, which reads messages and acts as the account. Anyone who wants those four tools runs full mode locally with their own cookie. See Hosting.

willhaben

What it does

Four public tools, no account needed:

Four account tools, requiring a session cookie:

Install

claude mcp add willmehr -- npx -y willmehr

Or from source:

npm install

npm run build npm run pack:kz # stage build/kleinanzeigen-mcp for publishing

willmehr publishes from the repo root. kleinanzeigen-mcp publishes from build/kleinanzeigen-mcp, staged by npm run pack:kz — it copies the built output the Kleinanzeigen entry point reaches (its own directory plus the shared mode module) and generates a manifest around it, so both packages ship the same commit at the same version. server.json and server.kleinanzeigen.json are the matching MCP registry entries.

Register it with Claude Code:

claude mcp add willmehr -- node "$PWD/dist/index.js"

Or in a client's MCP config:

{

"mcpServers": { "willmehr": { "command": "node", "args": ["/path/to/willmehr/dist/index.js"], "env": { "WILLHABEN_COOKIE": "BBX_JSESSIONID=...; x-bbx-csrf-token=..." } } } }

Authentication

willhaben authenticates through Keycloak with PKCE, so there is no username/password grant to automate. Instead, lift the session from a logged-in browser:

1. Log in to willhaben.at, then visit your profile or messages so the page loads an authenticated endpoint.
2. DevTools → Network → export dropdown → "Export HAR (with sensitive data)". The plain download button strips cookies and produces a file this cannot use.
3. npm run session -- ~/Downloads/www.willhaben.at.har
4. npm run check:auth

npm run session writes .env (mode 0600, gitignored) and never prints cookie values. npm run check:auth exercises all four account tools and stops at the first 401 rather than repeatedly failing auth against your account.

The cookie must contain BBX_JSESSIONID (the session) and x-bbx-csrf-token. The CSRF token is read out of the cookie automatically — willhaben's web app mirrors that cookie into a same-named request header on every /webapi/ call, and the server reproduces that. WILLHABEN_CSRF_TOKEN only exists to override it.

The server loads .env from the package root itself, so MCP clients don't need to pass the cookie through their config.

Sessions expire faster than the cookie claims

BBX_JSESSIONID is sent with a five-day Max-Age, but the server invalidates it well before that — a session captured and replayed 38 minutes later was already rejected. It is not IP- or header-binding: the same jar, replayed verbatim with the browser's complete header set from the same machine and IP, still returns 401 while anonymous requests continue to work.

Treat the session as short-lived. Re-run npm run session right before you need the account tools, rather than expecting a capture to keep working for days.

Environment variables

Using it well

Resolve ids before filtering. Categories and brands are opaque integers. Ask willhaben_discover_filters first — it returns each filter value with its id *and* a hit count for your current query:

Which laptop brands have listings under €300 in Vienna right now?

Narrow before ranking deals. willhaben_find_deals compares each listing against the median of its result set, so the query has to describe one kind of item. Searching thinkpad mixes €900 laptops with €5 docking stations and every "discount" it reports is noise. Searching thinkpad x1 carbon inside category 5831 (Notebooks) with priceFrom: 150 gives a median worth measuring against.

Watch for `suspiciouslyCheap`. Any listing under 20% of the median is flagged. Sometimes that's a genuine bargain; more often it's a placeholder price, a parts-only listing, or bait. The flag is a prompt to read the ad, not a verdict.

Sniping. Combine sort: "newest" with maxAgeHours: 2 to see only what appeared in the last couple of hours.

Example

Find me underpriced ThinkPad X1 Carbons from private sellers in Vienna, posted in

the last day, and tell me which are worth messaging about.

The agent chains willhaben_discover_filters → willhaben_find_deals → willhaben_get_ad on the top candidates to check seller age and ad text.

How it works

Notes from the HAR analysis, since none of this is documented publicly:

• `x-wh-client` is required. Every /webapi/ route returns a bare 400 with an empty body without it. This looks exactly like a malformed query parameter and is the single easiest thing to get stuck on.
• Search needs no cookies at all. Only account routes do.
• Filters are self-describing. Search responses carry navigatorGroups[], where each facet declares the query parameter it maps to and every legal value with a hit count. willhaben_discover_filters is a thin projection of that, which is why it stays correct when willhaben adds categories.
• Sort ids are undocumented integers. Verified empirically: 1 newest, 3 price ascending, 4 price descending, 0 relevance.
• There is no public single-ad JSON endpoint. publicapi.willhaben.at and api.willhaben.at both refuse anonymous callers. The ad page is Next.js, so the full payload is read from __NEXT_DATA__, using the lighter /_next/data/ /...json route when the buildId is known and falling back to HTML when willhaben redeploys and the id rotates.
• Every field arrives as a `{name, values[]}` bag. src/normalize.ts flattens it.

Rate limiting and terms

Requests are serialised through a single queue with a 400 ms floor between them, plus exponential backoff with jitter on 429/5xx. Please leave that in place.

Be aware that willhaben's robots.txt states *"It is expressively forbidden to use spiders, search robots or other automatic methods to access willhaben.at"*, disallows /webapi/, and specifically disallows the keyword, PRICE_FROM, PRICE_TO and periode parameters this server uses. Their Terms of Use likewise prohibit automated copying without consent. This tool performs exactly that kind of access.

That is a real constraint, not a formality: it's your account that would be suspended. This is built for personal, low-volume, occasional use against your own account. Don't point it at bulk collection, don't redistribute the data, and don't run it on a tight schedule.

Prior art

aliildan/willhaben-mcp covers more verticals (cars, real estate, jobs) but is anonymous-only and has no price analysis. If you want broad read-only browsing rather than deal hunting on the marketplace, use that one instead.

Kleinanzeigen

A port of jnslmk/kleinanzeigen-mcp (Python) to TypeScript, covering kleinanzeigen.de, Germany's largest classifieds site. No account needed.

Tools

The intended flow is kleinanzeigen_search → pick interesting ids → kleinanzeigen_get_listings_batch. Search result