Kleinanzeigen MCP Server: Live-Daten als Tools für KI-Clients

MCP klingt erst einmal abstrakt. Model Context Protocol ist aber im Kern eine einfache Idee: Ein KI-Client bekommt Werkzeuge, die er kontrolliert aufrufen kann.

Für Kleinanzeigen-Daten ist das nützlich, weil viele Fragen nicht mit einer einzelnen Suche erledigt sind. Ein guter Recherche-Workflow sucht zuerst passende Inserate, lädt danach Details nach, prüft Verkäufer-Kontext, schärft Standort- oder Kategorie-Filter nach und baut am Ende eine Shortlist.

Ohne MCP baust du diese Reihenfolge selbst in Code. Mit MCP kann ein kompatibler LLM-Client die passenden Kleinanzeigen-Tools direkt verwenden.

Die Grundidee

Der Kleinanzeigen MCP Server ist eine zusätzliche Oberfläche auf der bestehenden Live-API.

Ein normaler REST-Client ruft feste HTTP-Endpunkte auf. Ein MCP-Client verbindet sich mit einem Server, liest dessen Tool-Liste und kann diese Tools bei Bedarf ausführen. Das Modell bekommt also nicht einfach einen riesigen JSON-Dump, sondern klar benannte Werkzeuge mit validierten Eingaben.

Bei uns bedeutet das:

Der Client verbindet sich mit https://api.kleinanzeigen-agent.de/mcp.
Er sendet deinen API-Key als Bearer Token.
Er entdeckt Tools wie search_kleinanzeigen oder get_kleinanzeigen_ad.
Er ruft diese Tools über MCP/Streamable HTTP auf.
Die Tools verwenden dieselben Live-Daten, Credits, Rate Limits und Antwortformate wie die REST API.

Der Server gibt dem Modell keinen freien Datenbankzugriff. Er stellt nur definierte Kleinanzeigen-Werkzeuge bereit.

Was der MCP Server kann

Der Server deckt die wichtigsten Live-Funktionen der API ab:

Tool	Zweck
`search_kleinanzeigen`	Live-Inserate suchen
`get_kleinanzeigen_ad`	Inseratdetails laden
`get_kleinanzeigen_ad_status`	Prüfen, ob ein Inserat noch aktiv ist
`get_kleinanzeigen_seller_profile`	Öffentliches Verkäuferprofil laden
`get_kleinanzeigen_seller_ads`	Weitere Inserate eines Verkäufers laden
`list_kleinanzeigen_categories`	Kategoriebaum laden
`get_kleinanzeigen_category_metadata`	Felder einer Kategorie ansehen
`get_kleinanzeigen_category_search_metadata`	Suchfilter einer Kategorie laden
`search_kleinanzeigen_locations`	Standorte suchen
`get_kleinanzeigen_location`	Standortdetails laden

Das ist bewusst keine zweite Datenlogik. Die Tools nutzen dieselben Service-Funktionen wie /api/v2/kleinanzeigen/.... Dadurch bleiben Filter, normalisierte Felder, Fehlercodes, Credit-Abrechnung und Upstream-Behandlung konsistent.

Wie ein Tool-Aufruf abläuft

Technisch passiert bei einem MCP-Aufruf ungefähr das:

Dein MCP-Client sendet eine JSON-RPC-Nachricht an POST /mcp.
Der Backend-Guard prüft Host und Origin.
Authorization: Bearer klaz_live_... wird wie ein normaler API-Key authentifiziert.
Der planbasierte Rate Limiter prüft, ob der Account gerade anfragen darf.
Das Tool validiert seine Eingaben mit den gleichen Schemas wie die REST API.
Der Live-Call wird mit Credits abgerechnet.
Das Ergebnis kommt als MCP Tool Content zurück, inklusive normalisiertem JSON.

Wichtig: Ungültige Tool-Argumente kosten keine Credits. Wenn ein Live-Call wegen eines Upstream-Problems fehlschlägt, wird der Credit wie bei der REST API zurückerstattet.

Beispiel aus der Praxis

Angenommen, du suchst ein bestimmtes iPhone-Modell im Umkreis von Berlin. Du willst nicht nur die billigsten Treffer sehen, sondern eine kleine Einschätzung:

Welche Angebote wirken realistisch?
Welche Inserate bieten Versand?
Welche Verkäufer haben weitere ähnliche Artikel?
Welche Treffer sind privat oder gewerblich?
Welche Preise sind auffällig niedrig?

Mit REST würdest du diesen Ablauf selbst bauen: Suche ausführen, Treffer sortieren, Details abrufen, Verkäufer prüfen, Ergebnis formatieren.

Mit MCP kannst du dem Client eine Aufgabe geben:

Suche private iPhone 15 Angebote im Umkreis von 25 km um Berlin.
Lade Details für die 5 günstigsten Treffer nach und gib mir eine Tabelle mit Preis, Standort, Versand, Verkäufer und URL.

Ein guter MCP-Client kann daraus mehrere Tool-Aufrufe machen und die Ergebnisse danach verständlich zusammenfassen.

Authentifizierung

Der MCP Server nutzt denselben API-Key wie die normale Kleinanzeigen Agent API. Empfohlen ist der Bearer-Header:

Authorization: Bearer klaz_live_...

Aus Kompatibilitätsgründen funktioniert auch der bestehende Header:

klaz_key: klaz_live_...

Der Endpoint ist:

https://api.kleinanzeigen-agent.de/mcp

Dein Key gehört in die Secret-Verwaltung deines MCP-Clients, nicht in einen Prompt und nicht in eine URL. Wenn ein Key versehentlich geteilt wurde, rotierst du ihn im Dashboard.

Beispiel-Config

Viele MCP-Clients erlauben Remote-Server mit eigenen Headern. Die Konfiguration sieht sinngemäß so aus:

{
  "mcpServers": {
    "kleinanzeigen-agent": {
      "url": "https://api.kleinanzeigen-agent.de/mcp",
      "headers": {
        "Authorization": "Bearer klaz_live_..."
      }
    }
  }
}

Danach kann der Client die Tools selbst entdecken. Welche Oberfläche genau du dafür nutzt, hängt vom MCP-Client ab. Wichtig sind URL, Streamable HTTP und der Authorization Header.

Credits und Limits

MCP-Aufrufe kosten dieselben Credits wie die passenden REST-Endpunkte.

Aktion	Kosten
Suche	1 Credit
Inseratdetails	1 Credit
Inseratstatus	1 Credit
Verkäuferprofil	1 Credit
Verkäufer-Inserate	2 Credits
Views mit `include_views=true`	+1 Credit
Kategorien, Metadaten, Standorte	je 1 Credit

Ungültige Tool-Argumente verbrennen keine Credits. Wenn ein Live-Call wegen eines Upstream-Problems fehlschlägt, wird der Credit wie bei der API automatisch zurückerstattet.

Rate Limits hängen weiter am Plan. Der MCP Server umgeht also nichts — er ist nur eine andere Oberfläche für dieselbe Plattform.

MCP, REST API oder Webhook?

Alle drei Varianten haben ihren Platz:

Schnittstelle	Am besten für
REST API	Dein eigenes Backend, feste Jobs, eigene UI, deterministische Integrationen
MCP Server	LLM-Clients, Recherche-Assistenten, agentische Workflows, interaktive Analyse
Webhooks	Dauerhaftes Monitoring gespeicherter Suchfilter und automatische Benachrichtigungen

Wenn du genau weißt, welche Requests dein System ausführen soll, nimm REST. Wenn ein Modell während der Aufgabe entscheiden soll, welche Daten es als nächstes braucht, nimm MCP. Wenn du neue Inserate automatisch überwachen willst, nimm Webhooks.

Was dein MCP-Client können muss

Für die Verbindung brauchst du einen MCP-Client, der Remote-Server über HTTP unterstützt und eigene Header senden kann. Der wichtige Header ist:

Authorization: Bearer klaz_live_...

Wenn dein Client keine eigenen Header für MCP Server erlaubt, kannst du den Server dort aktuell nicht direkt verbinden. Nutze dann die REST API oder einen MCP-Client, der Header unterstützt.

Wo MCP besonders stark ist

MCP lohnt sich vor allem dort, wo Recherche mehrstufig ist:

Deal-Recherche: Der Client sucht Angebote, lädt Details nach, prüft Verkäufer-Kontext und fasst die besten Treffer zusammen.

Marktanalyse: Der Client sammelt Suchergebnisse für mehrere Kategorien oder Standorte und erstellt daraus Preisbereiche oder Auffälligkeiten.

Support und Operations: Du kannst mit einem internen LLM schneller nachvollziehen, welche Live-Daten ein Nutzer für eine bestimmte Suche sehen würde.

Agenten und Automationen: Ein Agent kann abhängig vom Zwischenergebnis entscheiden, ob er weitere Details, Kategorien oder Standorte braucht.

Grenzen und Sicherheit

Der MCP Server speichert keine Inserate und ersetzt keinen Webhook. Wenn du dauerhaft neue Inserate überwachen willst, ist der Kleinanzeigen Webhook der bessere Weg. MCP ist ideal für interaktive Recherche, Analyse und agentische Workflows.

Dein API-Key bleibt in deinem MCP-Client und wird nur als Header an unseren Server gesendet. Schreibe den Key nicht in Prompts, Chatnachrichten oder öffentliche Config-Dateien.

Außerdem gilt: Ein LLM kann Fehler machen. Für produktive Entscheidungen solltest du wichtige Ergebnisse immer mit IDs, Preisen, URLs und Zeitpunkten ausgeben lassen und bei Bedarf selbst validieren.

Jetzt ausprobieren

Die vollständige Tool-Liste, Setup-Hinweise und häufige Fehler findest du in der MCP Dokumentation. Deinen API-Key verwaltest du im Dashboard; Account, Plan und Guthaben liegen wie gewohnt unter /app/abrechnung.

Wenn du einen interessanten MCP-Workflow mit Kleinanzeigen-Daten baust, melde dich gern unter [email protected].