Skip to main content
Glama
Vinted MCP and CLI Server

Vinted MCP and CLI Server

πŸ›οΈ Vinted MCP & CLI Server

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

npm version CI License: MIT Node β‰₯18


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.


Related MCP server: qontoctl

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 -y -p @googlarz/vinted-client vinted 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 (minimum 5)
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

# Resolve size labels to IDs, or let search do it for you
vinted sizes M L XL --country de
vinted search "levi 501" --size M,L
vinted search "levi 501" --size-ids 206,207,208

# Filter by color (name auto-resolved)
vinted search "north face jacket" --color black --country fr

# Cross-country compare with filters (size M only)
vinted compare "adidas samba" --size-ids 103 --all-countries --output table

# Seller due-diligence
vinted feedback 987654 --country fr --output table

# Browse colors and size groups
vinted colors --output table
vinted size-groups --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

feedback <id>

Seller/buyer reviews (paginated)

compare <query>

Price comparison across countries with optional filters

brands <query>

Look up brand IDs by name

categories

Browse the category tree

colors

List all color options with IDs

size-groups

List all size groups with IDs

sizes <labels...>

Resolve size labels ("M", "42") to numeric IDs

trending

Newest / trending listings

debug

Inspect session cookie names (--show-cookie to print values)

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 <labels>

Size labels (auto-resolved to IDs, e.g. --size M,L or --size 42,43)

--size-ids <ids>

Comma-separated size IDs (vinted sizes M L to resolve)

--color-ids <ids>

Comma-separated color IDs (vinted colors to browse)

--color <names>

Color names (auto-resolved to IDs, e.g. --color black,white)

--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

--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, minimum 5s)

Result limits. Vinted serves search results in fixed pages of 96, so --limit only truncates a page, and at most 960 results are reachable per query. Search results carry the listing's brand, size and condition as Vinted displays them (localised to the country site, e.g. "Très bon état") and the seller's numeric ID but not the username — use vinted item <id> or vinted seller <id> for that. Vinted's catalog has no date filter, so there is no --date-from/--date-to; use --sort newest_first.


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", "-p", "@googlarz/vinted-client", "vinted-mcp"]
    }
  }
}

Setup β€” Claude Code

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

MCP Tools

Tool

Description

search_items

Search with full filter support (brand, size, color, condition, price)

search_all_items

Like search_items but auto-paginates and returns all results

get_new_items

Newest listings for a query; pass the previous latestId as afterId to get only what is new

get_item

Item detail by ID or URL

get_seller

Seller profile

get_seller_items

Active listings for a seller

get_seller_feedback

Paginated buyer/seller reviews with star ratings

compare_prices

Multi-country price stats (median, mean, stdDev, min, max) with filters

get_trending

Trending / newest listings

search_brands

Brand lookup β€” returns IDs for use in filters

get_categories

Category tree β€” returns IDs for use in filters

get_colors

All color options with hex codes and IDs

get_size_groups

All size groups with IDs (Women's, Men's, Shoes, Kids…)

resolve_size_ids

Resolve size labels ("M", "42", "XL") to numeric filter IDs

resolve_color_ids

Resolve color names ("black", "navy blue") to numeric filter IDs

Brand, size and color names passed to search_items, search_all_items, get_new_items and compare_prices are resolved automatically. If none of the names resolve the call fails (rather than silently searching unfiltered); if only some do, the result includes a warnings array. Browser mode for get_item is not available to MCP callers β€” the server operator enables it with VINTED_BROWSER=1.

MCP over HTTP

By default the server speaks stdio. For a network transport:

VINTED_MCP_TRANSPORT=http VINTED_MCP_TOKEN=choose-a-long-random-secret npx -y -p @googlarz/vinted-client vinted-mcp
# listens on http://127.0.0.1:3001/mcp β€” send `Authorization: Bearer <token>`

Without VINTED_MCP_TOKEN the server only accepts loopback Host headers and rejects browser (Origin) requests, and it refuses to bind to a non-loopback VINTED_MCP_HOST. Set a token whenever the port is reachable by anything you don't fully trust.

MCP Prompts

Built-in prompt templates for common workflows β€” use them from any MCP-compatible client:

Prompt

Arguments

Description

find-bargains

query, country?, maxPrice?

Find items priced below the median β€” highlights potential deals

seller-check

sellerId, country?

Due-diligence check β€” profile, reviews, listings

price-comparison

query

Rank all countries by median price, recommend cheapest market

wardrobe-hunt

brand, size?, color?, country?

Brand + size + color search with auto-resolved IDs

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"

"Is seller #987654 trustworthy? Check their reviews and listings."

"Find black Levi's 501 jeans size 32 β€” use the wardrobe-hunt prompt"


Library Usage

import { VintedClient, opSearch, opCompare, opSearchAll, opGetNewItems } 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 (report.failed lists countries that errored)
const report = await opCompare(client, {
  query: 'air jordan 1 retro',
  countries: ['fr', 'de', 'uk', 'it'],
});

// Poll for new listings: keep the cursor between calls
let cursor: number | undefined;
const fresh = await opGetNewItems(client, { query: 'air jordan 1', country: 'fr', afterId: cursor });
cursor = fresh.latestId ?? cursor;

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 (one bootstrap per country, shared by concurrent requests).

  2. Reads search results from the catalog page. Vinted removed its JSON catalog endpoint; the server-rendered /catalog page embeds the result list in its Next.js payload, which is parsed here. Sellers, feedback, brands, colors and sizes still come from the private JSON API (/api/v2/...).

  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 (kept in a separate cache so searches cannot evict it). Identical concurrent requests share one network call.

  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 (at most 2 browsers run at once)

VINTED_MCP_TRANSPORT

http to serve MCP over HTTP instead of stdio

VINTED_MCP_TOKEN

Bearer token required by the HTTP transport (mandatory for non-loopback hosts)

VINTED_MCP_HOST / VINTED_MCP_PORT / VINTED_MCP_PATH

HTTP bind address (default 127.0.0.1), port (3001) and path (/mcp)


Requirements

  • Node.js β‰₯ 18

  • Optional: playwright + puppeteer-extra-plugin-stealth for --browser / VINTED_BROWSER=1 mode


License

MIT Β© googlarz


Available Tools

15 tools
compare_pricesA

Compare prices for a search query across multiple Vinted country sites simultaneously. Returns median, mean, stdDev, min, max, and sample count per country along with the local currency. Supports the same brand/size/color/condition filters as search_items for precise cross-country comparisons. Useful for finding the cheapest market or understanding cross-border price gaps.

Inputs: query (required), brand, limit, sizeIds, +5 more.

get_categoriesA

Fetch the full Vinted category tree for a country. Returns a flat list of all categories and subcategories with their numeric IDs, names, parent IDs, and item counts. Pass a categoryId to search_items or search_all_items to restrict results to a department (e.g. women's clothing, men's shoes, electronics). Results are cached for 1 hour.

Inputs: query, country.

get_colorsA

Fetch the complete list of Vinted color options available as search filters. Returns every color with its numeric ID, display name, hex color code, short code (e.g. "BLACK"), and sort order. Pass the returned IDs to search_items.colorIds or search_all_items.colorIds to restrict results to specific colors. Results are cached for 1 hour β€” color catalogues change rarely.

Inputs: country.

get_itemA

Fetch complete item details by Vinted item ID (with country) or by a direct Vinted item URL. Returns title, price, currency, brand, size, condition, full description, all photo URLs, creation date, item URL, favourite count, and seller username/ID. Automatically falls back to HTML scraping when the JSON API is unavailable.

Inputs: url, itemId, country.

get_new_itemsA

Fetch the most recently listed items for a search query (newest first). To monitor a search, call it repeatedly and pass the previous response's latestId as afterId β€” only items listed since then are returned (truncated: true means more than perPage arrived; raise perPage or poll more often). Supports the same filters as search_items (brand, category, size, color, price, condition).

Inputs: query (required), size, brand, color, +10 more.

get_sellerA

Fetch a seller's public profile by their numeric user ID. Returns username, active listing count, feedback reputation score (0–1 float), total feedback count, country code, and profile URL. Use get_seller_feedback to read review texts and star ratings, and get_seller_items to browse their listings.

Inputs: sellerId (required), country.

get_seller_feedbackA

Fetch paginated buyer and seller feedback reviews for a Vinted user. Each entry includes the review text, star rating (1–5), feedback type (1=negative, 2=neutral, 3=positive), reviewer username, timestamp, and the associated item ID. Use this to assess seller trustworthiness and reliability before making a purchase.

Inputs: sellerId (required), page, limit, country.

get_seller_itemsA

List all items currently for sale by a specific seller, paginated. Returns the same fields as search_items (title, price, brand, size, condition, photo URL, item URL). Useful for browsing a seller's full catalogue after finding them via search_items or get_seller.

Inputs: sellerId (required), page, limit, country.

get_size_groupsA

Fetch all Vinted size groups with their constituent size IDs and labels. Returns a list of size groups (e.g. "Women's clothing", "Men's shoes", "Kids 2–8 yrs") β€” each containing the group ID, caption, description, and an array of sizes with numeric IDs and display titles (e.g. "XS", "42", "12 UK"). Pass individual size IDs from the sizes array to search_items.sizeIds or search_all_items.sizeIds to filter listings to an exact size. Results are cached for 1 hour.

Inputs: country.

resolve_color_idsA

Resolve color names (e.g. "black", "white", "navy") to numeric Vinted color IDs for use in search_items.colorIds and search_all_items.colorIds. Matching is case-insensitive and also works with Vinted's internal color codes (e.g. "BLACK", "NAVY_BLUE"). Alternatively, pass color names directly to search_items.color[] and they will be resolved automatically.

Inputs: colors (required), country.

resolve_size_idsA

Resolve human-readable size labels (e.g. "M", "42", "XL", "12 UK") to numeric Vinted size IDs suitable for use in search_items.sizeIds and search_all_items.sizeIds. Returns matched IDs with the group they belong to (e.g. "Women's clothing"), and a list of any labels that could not be resolved. Because "M" or "42" appear in multiple size groups (women's, men's, kids'), multiple IDs may be returned per label β€” pass them all to sizeIds to cast a wide net, or filter by group name if you need a specific category.

Inputs: sizes (required), country.

search_all_itemsA

Search Vinted listings and automatically paginate through all results, returning up to maxItems items in a single call. Use this instead of search_items when you need comprehensive results β€” e.g. "find all Nike shoes under €30" or "list every item in size M from this brand". Pages are fetched concurrently for speed. Returns the same item fields as search_items.

Inputs: query (required), size, brand, color, +11 more.

search_brandsA

Search Vinted's brand catalogue by keyword. Returns matching brands with their numeric IDs, slugs, total item counts, and favourite counts. Pass the returned IDs to search_items.brandIds, or use search_items.brand[] to pass names and have them resolved automatically.

Inputs: query (required), limit, country.

search_itemsA

Search Vinted second-hand listings with rich filters across 19 country sites. Returns a paginated list of items β€” each with title, price, currency, brand, size, condition, photo URL, item URL, favourite count, and seller info. Use get_categories to discover valid categoryId values and search_brands to resolve brand names to IDs. For comprehensive multi-page results use search_all_items instead.

Inputs: query (required), page, size, brand, +11 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 15 tools

    Disambiguation4/5

    Most tools target a distinct resource or action and the descriptions actively cross-reference each other (e.g. search_items points to search_all_items, resolve_color_ids points to get_colors). The main confusable pair is get_trending vs get_new_items, since both return recency-ordered items, with only country-scoping vs query+monitoring to tell them apart; the resolve_* vs get_* catalog pairs are related but functionally distinct.

    Naming Consistency5/5

    Every tool follows a clean snake_case verb_noun pattern (search_items, get_item, compare_prices, resolve_size_ids, get_seller_feedback). Verbs are used consistently and predictably across the whole set.

    Tool Count5/5

    15 tools is well scoped for a marketplace search/browse server, with each tool covering a distinct capability (search, detail, price comparison, taxonomy lookups, seller data). Nothing feels padded or redundant.

    Completeness4/5

    Coverage is strong for a read-only browsing server: search with rich filters, item details, cross-country price comparison, trending/new items, taxonomy lookups (categories, colors, sizes, brands), and seller profile/feedback/items. Minor gaps exist since it exposes favourite counts but offers no watchlist or seller-messaging actions.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      This MCP scraps vinted for product info. Disclaimer: This script is designed for educational purposes only. It is intended to demonstrate web scraping techniques and should not be used for any commercial or personal gain. Please note that using this software may violate the terms of service of Vint
      149
      GPL 3.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server for Vinted search and analysis that provides tools to search listings, fetch item details, inspect seller profiles, compare prices across countries, and surface trending items.
      163 npm
      36
      AGPL 3.0