🛍️ Vinted MCP & CLI 服务器

让你的 AI 助手能够访问 Vinted — 在 19 个国家/地区进行搜索、比价和追踪卖家。

npm version License: MIT Node ≥18

理念

Vinted 没有公开的 API。此包填补了这一空白 — 它允许 AI 助手通过 Model Context Protocol 直接与 Vinted 对话。

将其连接到 Claude、Cursor 或任何支持 MCP 的助手，只需询问：

“帮我在德国找一件 60 欧元以下的 North Face 夹克，成色要在良好及以上”

“比较一下法国、意大利和英国的 Air Jordan 1 价格”

“卖家 #123456 目前在卖什么？有 20 欧元以下的吗？”

AI 会自动判断使用哪些过滤器，调用 Vinted，并给你一个直接的答案 — 无需手动搜索、筛选或切换标签页。

同时提供 CLI 工具 和 TypeScript 库 以供直接使用。

这是什么？

这是一个用于 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

命令

命令	描述
`search <query>`	使用完整的过滤器支持搜索商品
`item <id	url>`	获取完整的商品详情
`seller <id>`	卖家资料
`seller-items <id>`	卖家在售商品
`compare <query>`	跨国家价格比较
`brands <query>`	按名称查找品牌 ID
`categories`	浏览分类树
`trending`	最新/热门商品
`debug`	检查会话 cookie（用于故障排除）

全局标志

标志	描述
`--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 码，成色非常好”

“比较一下法国、德国和意大利的 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 环境变量。

环境变量

变量	描述
`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
可选：playwright + puppeteer-extra-plugin-stealth 用于 --browser / VINTED_BROWSER=1 模式

Vinted MCP and CLI Server