Vinted MCP and CLI Server
🛍️ Vinted MCP & CLI 服务器
让你的 AI 助手能够访问 Vinted — 在 19 个国家/地区进行搜索、比价和追踪卖家。
理念
Vinted 没有公开的 API。此包填补了这一空白 — 它允许 AI 助手通过 Model Context Protocol 直接与 Vinted 对话。
将其连接到 Claude、Cursor 或任何支持 MCP 的助手,只需询问:
“帮我在德国找一件 60 欧元以下的 North Face 夹克,成色要在良好及以上”
“比较一下法国、意大利和英国的 Air Jordan 1 价格”
“卖家 #123456 目前在卖什么?有 20 欧元以下的吗?”
AI 会自动判断使用哪些过滤器,调用 Vinted,并给你一个直接的答案 — 无需手动搜索、筛选或切换标签页。
同时提供 CLI 工具 和 TypeScript 库 以供直接使用。
Related MCP server: qontoctl
这是什么?
这是一个用于 Vinted 二手交易平台的 MCP 服务器、CLI 工具 和 TypeScript 库。它没有官方 API — 它通过公共目录页面引导会话 cookie,并调用 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命令
命令 | 描述 | |
| 使用完整的过滤器支持搜索商品 | |
`item <id | url>` | 获取完整的商品详情 |
| 卖家资料 | |
| 卖家在售商品 | |
| 跨国家价格比较 | |
| 按名称查找品牌 ID | |
| 浏览分类树 | |
| 最新/热门商品 | |
| 检查会话 cookie(用于故障排除) |
全局标志
标志 | 描述 | |
`--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 服务器
将 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/mcpMCP 工具
工具 | 描述 |
| 使用完整的过滤器支持进行搜索 |
| 按 ID 或 URL 获取商品详情 |
| 卖家资料 |
| 卖家的在售商品 |
| 跨国家价格比较 |
| 热门商品 |
| 品牌查找 |
| 分类树 |
连接后的示例提示词:
“帮我在德国找 70 欧元以下的 Nike Air Max 95,43 码,成色非常好”
“比较一下法国、德国和意大利的 North Face 羽绒服价格”
“监控卖家 #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 前端设置的身份验证 cookie。调用私有 JSON API (
/api/v2/...):使用这些 cookie,模拟浏览器请求头。自动重新引导:在遇到 401 错误时 — 令牌过期后,库会自动静默恢复。
按国家/地区限流:使用令牌桶算法(可配置突发和填充速率)以避免 429 错误。
缓存响应:使用 LRU+TTL — 搜索结果缓存 60 秒,分类等静态数据缓存 1 小时。
回退到 HTML 抓取:对于被 DataDome 拦截的商品页面,使用 HTML 抓取(JSON-LD + 正则表达式提取)。
并发预取 3 页:在
opSearchAll中并发预取,以在限流预算内最大化吞吐量。
代理支持
如果 Vinted 封锁了你的 IP(在云虚拟机和 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
可选:
playwright+puppeteer-extra-plugin-stealth用于--browser/VINTED_BROWSER=1模式
许可证
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