🛍️ Servidor MCP y CLI de Vinted

Dale a tu asistente de IA acceso a Vinted: busca, compara precios y sigue a vendedores en 19 países.

La idea

Vinted no tiene una API pública. Este paquete cierra esa brecha: permite que los asistentes de IA hablen directamente con Vinted a través del Model Context Protocol.

Conéctalo a Claude, Cursor o cualquier asistente compatible con MCP y simplemente pregunta:

"Búscame una chaqueta North Face por menos de 60 € en Alemania, en buen estado o mejor"

"Compara precios de Air Jordan 1 en Francia, Italia y el Reino Unido"

"¿Qué está vendiendo actualmente el vendedor #123456? ¿Algo por menos de 20 €?"

La IA determina qué filtros usar, llama a Vinted y te da una respuesta real: sin búsquedas, sin filtros, sin pestañas.

También se distribuye como una herramienta CLI y una biblioteca de TypeScript para uso directo.

¿Qué es esto?

Un servidor MCP, una herramienta CLI y una biblioteca de TypeScript para el mercado de segunda mano Vinted. No hay API oficial: inicia una cookie de sesión desde la página del catálogo público y llama a la API JSON privada que la aplicación web de Vinted utiliza internamente.

• 🤖 Servidor MCP: conéctalo a Claude, Cursor o cualquier asistente de IA con soporte para MCP

• 🖥️ Herramienta CLI: canaliza resultados, busca nuevos listados, compara precios desde tu terminal

• 📦 Biblioteca de TypeScript: importa opSearch, opCompare, etc. directamente en tu código

Instalación

npm install -g @googlarz/vinted-client

O ejecútalo sin instalar:

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

Inicio rápido con CLI

# 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

Comandos

Flags globales

Flags de búsqueda

Países admitidos

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

Servidor MCP

Integra Vinted en cualquier asistente de IA compatible con MCP (Claude, Cursor, etc.).

Configuración: Claude Desktop

Añadir a claude_desktop_config.json:

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

Configuración: Claude Code

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

Herramientas MCP

Ejemplos de prompts una vez conectado:

"Búscame Nike Air Max 95 por menos de 70 € en Alemania, talla 43, muy buen estado"

"Compara precios de una chaqueta acolchada North Face en Francia, Alemania e Italia"

"Vigila al vendedor #987654 y avísame cuando publique algo por menos de 30 €"

Uso de la biblioteca

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'],
});

Opciones del cliente

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
});

Cómo funciona

Vinted no tiene una API pública. Esta biblioteca:

1. Inicia una sesión accediendo a vinted.{cc}/catalog y capturando las cookies de autenticación que establece el frontend de Vinted.

2. Llama a la API JSON privada (/api/v2/...) con esas cookies, imitando los encabezados de solicitud del navegador.

3. Se reinicia automáticamente ante un error 401: los tokens caducan, la biblioteca se recupera silenciosamente.

4. Limita la tasa por país con un cubo de tokens (ráfaga + recarga configurables) para evitar errores 429.

5. Almacena en caché las respuestas con LRU+TTL: 60s para resultados de búsqueda, 1h para datos estáticos como categorías.

6. Recurre al scraping de HTML para páginas de artículos bloqueadas por DataDome (JSON-LD + extracción mediante regex).

7. Precarga 3 páginas simultáneamente en opSearchAll para maximizar el rendimiento dentro del límite de tasa.

Soporte de proxy

Si Vinted bloquea tu IP (común en máquinas virtuales en la nube y CI), configura un proxy:

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

También se respetan las variables de entorno estándar HTTPS_PROXY / HTTP_PROXY.

Variables de entorno

Requisitos

• Node.js ≥ 18

• Opcional: playwright + puppeteer-extra-plugin-stealth para el modo --browser / VINTED_BROWSER=1

Licencia

MIT © googlarz