Vinted MCP and CLI Server
🛍️ Vinted MCP & CLI 서버
AI 어시스턴트에게 Vinted 접근 권한을 부여하세요 — 19개국에 걸쳐 검색, 가격 비교, 판매자 추적을 수행할 수 있습니다.
아이디어
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 웹 앱이 내부적으로 사용하는 비공개 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명령어
명령어 | 설명 | |
| 전체 필터 지원을 통한 매물 검색 | |
`item <id | url>` | 전체 상품 상세 정보 가져오기 |
| 판매자 프로필 | |
| 판매자가 판매 중인 상품 | |
| 국가별 가격 비교 | |
| 이름으로 브랜드 ID 조회 | |
| 카테고리 트리 탐색 | |
| 최신 / 인기 매물 | |
| 세션 쿠키 검사 (문제 해결용) |
전역 플래그
플래그 | 설명 | |
`--output json | table` | 출력 형식 (기본값: |
| 국가 코드 (아래 참조) | |
| HTTP/HTTPS 프록시 (또는 | |
| 응답 캐시 비활성화 |
검색 플래그
플래그 | 설명 |
| 가격 범위 |
| 브랜드 이름 (ID로 자동 확인) |
| 쉼표로 구분된 브랜드 ID |
| 카테고리 ID ( |
| 쉼표로 구분된 사이즈 ID |
|
|
|
|
| 날짜 범위 필터 (YYYY-MM-DD) |
| 페이지를 순회하며 모든 결과 수집 |
|
|
| N초마다 새 매물 폴링 (기본값 60초) |
지원 국가
fr de uk it es nl pl pt be at lt cz sk hu ro hr fi dk se
MCP 서버
MCP 호환 AI 어시스턴트(Claude, Cursor 등)에 Vinted를 추가하세요.
설정 — 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/mcpMCP 도구
도구 | 설명 |
| 전체 필터 지원을 통한 검색 |
| ID 또는 URL로 상품 상세 정보 조회 |
| 판매자 프로필 |
| 판매자의 활성 매물 |
| 국가 간 가격 비교 |
| 인기 매물 |
| 브랜드 조회 |
| 카테고리 트리 |
연결 후 예시 프롬프트:
*"독일에서 €70 미만, 사이즈 43, 상태 매우 좋음인 나이키 에어 맥스 95를 찾아줘"
*"프랑스, 독일, 이탈리아 전역의 노스페이스 패딩 재킷 가격을 비교해줘"
*"판매자 #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/...) API를 호출합니다.자동 재부트스트랩: 401 오류 발생 시 토큰이 만료된 것으로 간주하여 라이브러리가 자동으로 복구합니다.
국가별 속도 제한: 429 오류를 방지하기 위해 토큰 버킷(구성 가능한 버스트 + 리필)을 사용하여 국가별로 속도를 제한합니다.
응답 캐싱: LRU+TTL을 사용하여 캐싱합니다 (검색 결과 60초, 카테고리 등 정적 데이터 1시간).
HTML 스크래핑 폴백: 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 환경 변수도 지원됩니다.
환경 변수
변수 | 설명 |
| HTTP/HTTPS 프록시 URL |
| 캐시 TTL (밀리초 단위, 기본값 |
| 국가당 초당 요청 수 (기본값 |
| 토큰 버킷 버스트 크기 (기본값 |
| 상품 상세 정보를 위해 스텔스 브라우저를 사용하려면 |
요구 사항
Node.js ≥ 18
선택 사항:
--browser/VINTED_BROWSER=1모드를 위한playwright+puppeteer-extra-plugin-stealth
라이선스
MIT © googlarz
Available Tools
15 toolscompare_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.
get_trendingA
Fetch the newest and trending items on Vinted for a given country, ordered by recency. Optionally scoped to a specific category. Useful for discovering what's currently popular, monitoring new arrivals, or finding deals as they are listed.
Inputs: limit, country, categoryId.
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
Scored across 15 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for Product Management
MCP Server for an Agent Task Marketplace
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceThis 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 Vint149GPL 3.0
- AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceAn 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 npm36AGPL 3.0
- MIT