🛍️ Vinted MCP & CLI サーバー

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

npm version License: MIT Node ≥18

コンセプト

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

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

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

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

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

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

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

これは何か？

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 がありません。このライブラリは以下の処理を行います：

vinted.{cc}/catalog にアクセスし、Vinted フロントエンドが設定する認証クッキーを取得してセッションをブートストラップします。
ブラウザのリクエストヘッダーを模倣し、それらのクッキーを使用してプライベートな JSON API (/api/v2/...) を呼び出します。
401 エラー発生時に自動的に再ブートストラップを行います。トークンは期限切れになるため、ライブラリはバックグラウンドで復旧します。
429 エラーを回避するため、トークンバケット（バーストとリフィルを設定可能）を使用して国ごとのレート制限を行います。
LRU+TTL を使用してレスポンスをキャッシュします（検索結果は60秒、カテゴリなどの静的データは1時間）。
DataDome によってブロックされたアイテムページに対しては、HTML スクレイピング（JSON-LD + 正規表現抽出）にフォールバックします。
レート制限の範囲内でスループットを最大化するため、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

Vinted MCP and CLI Server