Skip to main content
Glama
Vinted MCP and CLI Server

Vinted MCP and CLI Server

🛍️ Vinted MCP & CLI サーバー

AI アシスタントに Vinted へのアクセス権を与えましょう — 19 か国にわたる検索、価格比較、出品者の追跡が可能です。

npm version CI License: MIT Node ≥18


コンセプト

Vinted には公開 API がありません。このパッケージはそのギャップを埋めるもので、Model Context Protocol を介して AI アシスタントが Vinted と直接対話できるようにします。

Claude、Cursor、または MCP 対応のアシスタントに接続して、次のように尋ねるだけです:

「ドイツで60ユーロ以下のノースフェイスのジャケットを探して。状態は『良い』以上で」

「フランス、イタリア、イギリスのエアジョーダン1の価格を比較して」

「出品者 #123456 は現在何を出品している?20ユーロ以下のものはある?」

AI が使用すべきフィルターを判断し、Vinted を呼び出して回答を提供します。検索やフィルタリング、タブの切り替えは不要です。

また、直接使用するための CLI ツール および TypeScript ライブラリ としても提供されています。


Related MCP server: qontoctl

これは何か?

Vinted 二次流通マーケットプレイス向けの MCP サーバー、CLI ツール、および TypeScript ライブラリ です。公式 API は存在しないため、公開カタログページからセッションクッキーをブートストラップし、Vinted Web アプリが内部で使用しているプライベートな JSON API を呼び出します。

  • 🤖 MCP サーバー — Claude、Cursor、または MCP をサポートするあらゆる AI アシスタントにプラグイン可能

  • 🖥️ CLI ツール — 結果のパイプ処理、新規出品の監視、ターミナルからの価格比較

  • 📦 TypeScript ライブラリ — opSearch、opCompare などをコード内で直接インポート可能


インストール

npm install -g @googlarz/vinted-client

またはインストールせずに実行:

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

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

コマンド

コマンド

説明

search <query>

完全なフィルターサポートを備えた出品検索

`item <id

url>`

アイテムの詳細を取得

seller <id>

出品者プロフィール

seller-items <id>

出品者の販売中アイテム

compare <query>

国をまたいだ価格比較

brands <query>

名前によるブランド ID の検索

categories

カテゴリツリーの閲覧

trending

最新/トレンドの出品

debug

セッションクッキーの検査(トラブルシューティング用)

グローバルフラグ

フラグ

説明

`--output json

table`

出力形式 (デフォルト: json)

--country <cc>

国コード (下記参照)

--proxy <url>

HTTP/HTTPS プロキシ (または VINTED_PROXY_URL)

--no-cache

レスポンスキャッシュを無効化

検索フラグ

フラグ

説明

--price-min / --price-max

価格範囲

--brand <names>

ブランド名 (ID に自動解決)

--brand-ids <ids>

カンマ区切りのブランド ID

--category-id <n>

カテゴリ ID (vinted categories で閲覧)

--size-ids <ids>

カンマ区切りのサイズ ID

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

日付範囲フィルター (YYYY-MM-DD)

--all

ページを巡回して全結果を収集

--max-items <n>

--all の上限 (デフォルト 1000)

--watch [interval]

N 秒ごとに新規出品をポーリング (デフォルト 60秒)


対応国

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


MCP サーバー

Vinted を MCP 対応の AI アシスタント (Claude、Cursor など) に組み込みます。

セットアップ — Claude Desktop

claude_desktop_config.json に追加します:

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

セットアップ — Claude Code

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

MCP ツール

ツール

説明

search_items

完全なフィルターサポートによる検索

get_item

ID または URL によるアイテム詳細

get_seller

出品者プロフィール

get_seller_items

出品者のアクティブな出品

compare_prices

国をまたいだ価格比較

get_trending

トレンドの出品

search_brands

ブランド検索

get_categories

カテゴリツリー

接続後のプロンプト例:

「ドイツで70ユーロ以下の Nike Air Max 95 を探して。サイズ43、状態は『非常に良い』」

「フランス、ドイツ、イタリアのノースフェイスのダウンジャケットの価格を比較して」

「出品者 #987654 を監視して、30ユーロ以下の出品があったら教えて」


ライブラリの使用方法

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

クライアントオプション

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

仕組み

Vinted には公開 API がありません。このライブラリは以下の処理を行います:

  1. vinted.{cc}/catalog にアクセスし、Vinted フロントエンドが設定する認証クッキーを取得してセッションをブートストラップします。

  2. ブラウザのリクエストヘッダーを模倣し、それらのクッキーを使用してプライベートな JSON API (/api/v2/...) を呼び出します。

  3. 401 エラー発生時に自動的に再ブートストラップを行います。トークンは期限切れになるため、ライブラリはバックグラウンドで復旧します。

  4. 429 エラーを回避するため、トークンバケット(バーストとリフィルを設定可能)を使用して国ごとのレート制限を行います。

  5. LRU+TTL を使用してレスポンスをキャッシュします(検索結果は60秒、カテゴリなどの静的データは1時間)。

  6. DataDome によってブロックされたアイテムページに対しては、HTML スクレイピング(JSON-LD + 正規表現抽出)にフォールバックします。

  7. レート制限の範囲内でスループットを最大化するため、opSearchAll で3ページを並行してプリフェッチします。


プロキシサポート

Vinted が IP をブロックしている場合(クラウド VM や CI で一般的)、プロキシを設定してください:

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

標準の HTTPS_PROXY / HTTP_PROXY 環境変数もサポートされています。


環境変数

変数

説明

VINTED_PROXY_URL

HTTP/HTTPS プロキシ URL

VINTED_CACHE_TTL_MS

キャッシュ TTL (ミリ秒、デフォルト 60000)

VINTED_RATE_LIMIT_PER_SEC

国ごとの秒間リクエスト数 (デフォルト 3)

VINTED_RATE_LIMIT_BURST

トークンバケットのバーストサイズ (デフォルト 6)

VINTED_BROWSER

アイテム詳細にステルスブラウザを使用する場合は 1 に設定


要件

  • Node.js ≥ 18

  • オプション: --browser / VINTED_BROWSER=1 モードを使用する場合は playwright + puppeteer-extra-plugin-stealth


ライセンス

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