🛍️ Vinted MCP & CLI Server

Gib deinem KI-Assistenten Zugriff auf Vinted — durchsuche Artikel, vergleiche Preise und verfolge Verkäufer in 19 Ländern.

Die Idee

Vinted hat keine öffentliche API. Dieses Paket schließt diese Lücke — es ermöglicht KI-Assistenten, direkt mit Vinted zu kommunizieren über das Model Context Protocol.

Verbinde es mit Claude, Cursor oder einem anderen MCP-kompatiblen Assistenten und frage einfach:

"Suche mir eine North Face Jacke unter 60 € in Deutschland, Zustand gut oder besser"

"Vergleiche die Preise für Air Jordan 1 in Frankreich, Italien und Großbritannien"

"Was verkauft Verkäufer #123456 gerade? Irgendetwas unter 20 €?"

Die KI findet heraus, welche Filter zu verwenden sind, ruft Vinted auf und gibt dir eine echte Antwort — kein Suchen, kein Filtern, keine Tabs.

Ebenfalls als CLI-Tool und TypeScript-Bibliothek für die direkte Verwendung verfügbar.

Was ist das?

Ein MCP-Server, CLI-Tool und eine TypeScript-Bibliothek für den Second-Hand-Marktplatz Vinted. Es gibt keine offizielle API — es erstellt ein Sitzungs-Cookie von der öffentlichen Katalogseite und ruft die private JSON-API auf, die die Vinted-Web-App intern verwendet.

• 🤖 MCP-Server — verbinde dich mit Claude, Cursor oder einem beliebigen KI-Assistenten mit MCP-Unterstützung

• 🖥️ CLI-Tool — Ergebnisse weiterleiten, neue Angebote beobachten, Preise direkt vom Terminal aus vergleichen

• 📦 TypeScript-Bibliothek — importiere opSearch, opCompare usw. direkt in deinen Code

Installation

npm install -g @googlarz/vinted-client

Oder ohne Installation ausführen:

npx @googlarz/vinted-client search "levis 501"

CLI Schnellstart

# Search (JSON by default)
vinted search "levi's 501" --country fr

# Pretty table
vinted search "levi's 501" --country de --output table

# Filter by price, brand, condition
vinted search "adidas samba" \
  --price-min 20 --price-max 80 \
  --brand adidas \
  --condition new_with_tags,very_good \
  --output table

# Watch for new listings every 30s
vinted search "air jordan 1" --watch 30

# Walk all pages and collect up to 500 results
vinted search "vintage denim" --all --max-items 500

# Get a specific item (ID or URL)
vinted item 1234567
vinted item https://www.vinted.fr/items/1234567

# Seller profile + active listings
vinted seller 987654
vinted seller-items 987654 --output table

# Cross-country price comparison (6 countries by default)
vinted compare "north face jacket" --output table

# Browse category tree
vinted categories --query shoes --output table

# Look up brand IDs
vinted brands "stone island"

# What's trending right now
vinted trending --country fr --output table

Befehle

Globale Flags

Such-Flags

Unterstützte Länder

fr de uk it es nl pl pt be at lt cz sk hu ro hr fi dk se

MCP Server

Binde Vinted in jeden MCP-kompatiblen KI-Assistenten ein (Claude, Cursor, etc.).

Einrichtung — Claude Desktop

Füge dies zu claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "vinted": {
      "command": "npx",
      "args": ["-y", "@googlarz/vinted-client/mcp"]
    }
  }
}

Einrichtung — Claude Code

claude mcp add vinted -- npx -y @googlarz/vinted-client/mcp

MCP Tools

Beispiel-Prompts nach der Verbindung:

"Suche mir Nike Air Max 95 unter 70 € in Deutschland, Größe 43, Zustand sehr gut"

"Vergleiche die Preise für eine North Face Pufferjacke in Frankreich, Deutschland und Italien"

"Beobachte Verkäufer #987654 und sag mir Bescheid, wenn sie etwas unter 30 € einstellen"

Bibliotheksnutzung

import { VintedClient, opSearch, opCompare, opSearchAll } from '@googlarz/vinted-client';

const client = new VintedClient();

// Basic search
const results = await opSearch(client, {
  query: 'levi\'s 501',
  country: 'de',
  priceMax: 50,
  condition: ['very_good', 'good'],
  sortBy: 'price_low_to_high',
});

console.log(results.items);

// Collect all pages concurrently (3-page prefetch window)
const all = await opSearchAll(client, {
  query: 'vintage band tee',
  country: 'uk',
  maxItems: 300,
});

// Multi-country price comparison
const report = await opCompare(client, {
  query: 'air jordan 1 retro',
  countries: ['fr', 'de', 'uk', 'it'],
});

Client-Optionen

const client = new VintedClient({
  proxyUrl: 'http://proxy:8080',   // or VINTED_PROXY_URL env var
  cacheTtlMs: 60_000,              // response cache TTL (0 = disable)
  rateLimitPerSec: 3,              // requests/sec per country
  rateLimitBurst: 6,               // burst capacity
  timeoutMs: 20_000,               // per-request timeout
});

Funktionsweise

Vinted hat keine öffentliche API. Diese Bibliothek:

1. Startet eine Sitzung, indem sie vinted.{cc}/catalog aufruft und die Authentifizierungs-Cookies erfasst, die das Vinted-Frontend setzt.

2. Ruft die private JSON-API (/api/v2/...) mit diesen Cookies auf und ahmt die Request-Header des Browsers nach.

3. Startet bei 401 automatisch neu — Tokens laufen ab, die Bibliothek stellt die Verbindung im Hintergrund wieder her.

4. Ratenbegrenzung pro Land mit einem Token-Bucket (konfigurierbarer Burst + Auffüllung), um 429-Fehler zu vermeiden.

5. Cacht Antworten mit LRU+TTL — 60s für Suchergebnisse, 1h für statische Daten wie Kategorien.

6. Greift auf HTML-Scraping zurück, wenn Artikelseiten durch DataDome blockiert werden (JSON-LD + Regex-Extraktion).

7. Lädt 3 Seiten gleichzeitig vor in opSearchAll, um den Durchsatz innerhalb des Ratenlimits zu maximieren.

Proxy-Unterstützung

Wenn Vinted deine IP blockiert (häufig bei Cloud-VMs und CI), richte einen Proxy ein:

VINTED_PROXY_URL=http://user:pass@proxy:8080 vinted search "nike"
# or
vinted search "nike" --proxy http://user:pass@proxy:8080

Standard HTTPS_PROXY / HTTP_PROXY Umgebungsvariablen werden ebenfalls berücksichtigt.

Umgebungsvariablen

Anforderungen

• Node.js ≥ 18

• Optional: playwright + puppeteer-extra-plugin-stealth für den --browser / VINTED_BROWSER=1 Modus

Lizenz

MIT © googlarz