kleinanzeigen-mcp

An MCP server that lets an LLM search Kleinanzeigen.de, Germany's largest classifieds site. Built for self-hosting: one container, no API keys, no per-query credits.

Scraping is done by DanielWTE/ebay-kleinanzeigen-api, which is baked into the image at a pinned commit. This project is the MCP layer on top.

Tools

The intended flow is search_listings → pick interesting ids → get_listings_batch. Search results deliberately omit descriptions so a broad search does not blow up the model's context window.

Related MCP server: marketplace-search-mcp

Running it

docker run --rm -p 8000:8000 ghcr.io/jnslmk/kleinanzeigen-mcp:latest

The server speaks streamable HTTP at http://localhost:8000/mcp, with a plain GET /healthz for container healthchecks. Set MCP_TRANSPORT=stdio to run it as a local stdio server instead.

Chromium needs room to work — give the container at least 1.5 GB of memory.

Configuration

The KZ_MAX_* defaults are tuned for a chat agent making one request at a time. Raise them for throughput, at the cost of memory and a greater chance of tripping Kleinanzeigen's bot detection.

LibreChat

mcpServers:
  kleinanzeigen:
    type: streamable-http
    url: "http://kleinanzeigen-mcp:8000/mcp"
    timeout: 120000
    chatMenu: true

mcpSettings:
  allowedAddresses:
    - "kleinanzeigen-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 on purpose — a cold search has to start a browser context and load real pages.

Claude Code

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

Development

uv venv && uv pip install -e .
# The scrapers are not on PyPI, so point PYTHONPATH at a checkout of upstream:
git clone https://github.com/DanielWTE/ebay-kleinanzeigen-api.git /tmp/kz-api
pip install -r /tmp/kz-api/requirements.txt && playwright install chromium
PYTHONPATH=/tmp/kz-api python -m kleinanzeigen_mcp

Upgrading the scraper

UPSTREAM_SHA in the Dockerfile pins the upstream commit. It is pinned rather than tracking main because this server imports upstream's scraper functions directly — ultra_optimized_scrape_inserate, get_inserate_details_optimized and scrape_by_url — instead of going through its HTTP API. That avoids a second process and an HTTP hop, but it means an upstream refactor can break this image at runtime rather than at build time. Bump the SHA, rebuild, smoke-test each tool, then ship.

patches/astro-results-fields.patch rides on top of the pin: Kleinanzeigen's Astro relaunch (Sept 2026) dropped the classic card markup, and upstream's own fix restored adid/url/title/location but not price, description or date — the patch adds card-content fallbacks for those three. The Dockerfile applies it with git apply --check, so when the pin moves past code the patch no longer fits, the build fails loudly instead of silently shipping a regression. Upstream absorbing this fix is the exit condition for the patch — drop it the moment a newer pin makes it redundant.

Automated upstream updates

Renovate watches upstream main and opens a PR bumping UPSTREAM_SHA within an hour of each upstream commit (hourly run dedicated to the pin; a weekly pass covers the base image). Pin PRs are never automerged, and the patch --check above is the compatibility gate: any PR whose pin outgrows the patch goes red in CI.

Turning a red pin PR green is an AI-agent job: point a coding-agent session at the PR and have it review the upstream diff (git diff <old-pin>..<new-pin> in a clone of upstream), rework patches/ if the touched code overlaps, confirm the build is green, then smoke-test each tool against the rebuilt image before merging. Green pin PRs still deserve the tool smoke test — a clean apply says nothing about runtime behavior of the imported functions.

RENOVATE_TOKEN is a fine-grained GitHub PAT limited to this repository, with Contents, Commit statuses, Issues, Pull requests, and Workflows read/write plus Dependabot alerts read. It expires after 366 days; run scripts/setup-renovate-token.sh to create or rotate it and install the Actions secret without persisting its value locally.

Images

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

Caveats

Kleinanzeigen has no public API, so this scrapes the site with a headless browser. That means it can break whenever they change their markup, and heavy or parallel use may trip bot detection — particularly from a datacenter IP. Scraping is also at odds with Kleinanzeigen's terms of service. Keep it to personal-scale use.

License

MIT. Bundles DanielWTE/ebay-kleinanzeigen-api, also MIT — see LICENSE.