🛍️ 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 웹 앱이 내부적으로 사용하는 비공개 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 서버

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

MCP 도구

도구	설명
`search_items`	전체 필터 지원을 통한 검색
`get_item`	ID 또는 URL로 상품 상세 정보 조회
`get_seller`	판매자 프로필
`get_seller_items`	판매자의 활성 매물
`compare_prices`	국가 간 가격 비교
`get_trending`	인기 매물
`search_brands`	브랜드 조회
`get_categories`	카테고리 트리

연결 후 예시 프롬프트:

*"독일에서 €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 환경 변수도 지원됩니다.

환경 변수

변수	설명
`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