<div align="center">

🛍️ Vinted MCP & CLI Server

Give your AI assistant access to Vinted — search, compare prices, and track sellers across 19 countries.

</div>

---

The idea

Vinted has no public API. This package bridges that gap — it lets AI assistants talk directly to Vinted via the Model Context Protocol.

Connect it to Claude, Cursor, or any MCP-compatible assistant and just ask:

"Find me a North Face jacket under €60 in Germany, good condition or better"

"Compare prices for Air Jordan 1s across France, Italy and the UK"

"What is seller #123456 currently selling? Anything under €20?"

The AI figures out which filters to use, calls Vinted, and gives you a real answer — no searching, no filtering, no tabs.

Also ships as a CLI tool and TypeScript library for direct use.

---

What is this?

An MCP server, CLI tool, and TypeScript library for the Vinted secondhand marketplace. No official API — it bootstraps a session cookie from the public catalog page and calls the private JSON API the Vinted web app uses internally.

• 🤖 MCP server — plug into Claude, Cursor, or any AI assistant with MCP support
• 🖥️ CLI tool — pipe results, watch for new listings, compare prices from your terminal
• 📦 TypeScript library — import opSearch, opCompare, etc. directly in your code

---

Install

npm install -g @googlarz/vinted-client

Or run without installing:

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

---

CLI Quick Start

# 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

---

Commands

| Command | Description | |---|---| | search <query> | Search listings with full filter support | | item <id\|url> | Get full item detail | | seller <id> | Seller profile | | seller-items <id> | Items a seller has for sale | | compare <query> | Price comparison across countries | | brands <query> | Look up brand IDs by name | | categories | Browse the category tree | | trending | Newest / trending listings | | debug | Inspect session cookies (for troubleshooting) |

Global flags

| Flag | Description | |---|---| | --output json\|table | Output format (default: json) | | --country <cc> | Country code (see below) | | --proxy <url> | HTTP/HTTPS proxy (also: VINTED_PROXY_URL) | | --no-cache | Disable response cache |

Search flags

| Flag | Description | |---|---| | --price-min / --price-max | Price range | | --brand <names> | Brand names (auto-resolved to IDs) | | --brand-ids <ids> | Comma-separated brand IDs | | --category-id <n> | Category ID (vinted categories to browse) | | --size-ids <ids> | Comma-separated size IDs | | --condition <list> | new_with_tags, new_without_tags, very_good, good, satisfactory | | --sort <s> | relevance, price_low_to_high, price_high_to_low, newest_first | | --date-from / --date-to | Date range filter (YYYY-MM-DD) | | --all | Walk pages and collect all results | | --max-items <n> | Cap for --all (default 1000) | | --watch [interval] | Poll every N seconds for new listings (default 60s) |

---

Supported Countries

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

---

MCP Server

Drop Vinted into any MCP-compatible AI assistant (Claude, Cursor, etc.).

Setup — Claude Desktop

Add to claude_desktop_config.json:

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

Setup — Claude Code

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

MCP Tools

| Tool | Description | |---|---| | search_items | Search with full filter support | | get_item | Item detail by ID or URL | | get_seller | Seller profile | | get_seller_items | Active listings for a seller | | compare_prices | Multi-country price comparison | | get_trending | Trending listings | | search_brands | Brand lookup | | get_categories | Category tree |

Example prompts once connected:

"Find me Nike Air Max 95s under €70 in Germany, size 43, very good condition"

"Compare prices for a North Face puffer jacket across France, Germany and Italy"

"Watch seller #987654 and tell me when they list something under €30"

---

Library Usage

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 options

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

---

How it works

Vinted has no public API. This library:

1. Bootstraps a session by hitting vinted.{cc}/catalog and capturing the auth cookies the Vinted frontend sets.
2. Calls the private JSON API (/api/v2/...) with those cookies, mimicking browser request headers.
3. Re-bootstraps automatically on 401 — tokens expire, the library recovers silently.
4. Rate-limits per country with a token bucket (configurable burst + refill) to avoid 429s.
5. Caches responses with LRU+TTL — 60s for search results, 1h for static data like categories.
6. Falls back to HTML scraping for item pages blocked by DataDome (JSON-LD + regex extraction).
7. Prefetches 3 pages concurrently in opSearchAll to maximise throughput within the rate-limit budget.

---

Proxy support

If Vinted blocks your IP (common on cloud VMs and CI), set a proxy:

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 env vars are also respected.

---

Environment variables

| Variable | Description | |---|---| | VINTED_PROXY_URL | HTTP/HTTPS proxy URL | | VINTED_CACHE_TTL_MS | Cache TTL in ms (default 60000) | | VINTED_RATE_LIMIT_PER_SEC | Requests per second per country (default 3) | | VINTED_RATE_LIMIT_BURST | Token bucket burst size (default 6) | | VINTED_BROWSER | Set to 1 to use stealth browser for item detail |

---

Requirements

• Node.js ≥ 18
• Optional: playwright + puppeteer-extra-plugin-stealth for --browser / VINTED_BROWSER=1 mode

---

License

MIT © googlarz

---

<div align="center"> _{Not affiliated with Vinted UAB. Use responsibly.} </div>