vinted-mcp-server

A Model Context Protocol (MCP) server for interacting with the Vinted marketplace. Enables AI assistants to search, browse, and discover second-hand items on Vinted.

Features

• Search items — Full-text search with filters (price, brand, size, color, condition, sort)

• Item details — Full item info including description, photos, seller profile, and condition

• User profiles — Seller ratings, reviews, item counts, and activity

• User items — Browse all items listed by a specific user

• Brand search — Find brand IDs for use in search filters

• Rate limiting — Token bucket rate limiter to avoid API bans

• Caching — In-memory LRU cache with TTL for fast repeated queries

• Retry logic — Exponential backoff for transient errors

• Session management — Puppeteer-based with Cloudflare bypass

• Token-efficient — Concise markdown responses optimized for LLM consumption

Quick Start

Prerequisites

• Node.js 20+

Using npx (zero-install)

This server communicates via stdio (JSON-RPC) and is designed to be launched by an MCP client, not run directly in a terminal. Configure it in your MCP client as shown below.

Install from source

git clone https://github.com/Rbillon59/vinted-mcp-server.git
cd vinted-mcp-server
npm install
npm run build

Usage with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "vinted": {
      "command": "npx",
      "args": ["@rbillon59/vinted-mcp-server"],
      "env": {
        "VINTED_DOMAIN": "www.vinted.fr"
      }
    }
  }
}

{
  "mcpServers": {
    "vinted": {
      "command": "node",
      "args": ["/absolute/path/to/vinted-mcp-server/dist/index.js"],
      "env": {
        "VINTED_DOMAIN": "www.vinted.fr"
      }
    }
  }
}

Usage with Claude Code CLI

Add to your Claude Code settings (~/.claude/settings.json or project .mcp.json):

{
  "mcpServers": {
    "vinted": {
      "command": "npx",
      "args": ["@rbillon59/vinted-mcp-server"],
      "env": {
        "VINTED_DOMAIN": "www.vinted.fr"
      }
    }
  }
}

Usage with Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "vinted": {
      "command": "npx",
      "args": ["@rbillon59/vinted-mcp-server"]
    }
  }
}

Usage with Docker

docker build -t vinted-mcp-server .
docker run -i --rm -e VINTED_DOMAIN=www.vinted.fr vinted-mcp-server

Available Tools

search_items

Search the Vinted catalog with filters.

get_item_details

Get detailed information about a specific item.

Returns: title, price, description, brand, size, condition, colors, seller info (rating, location), photos, stats (views, favorites).

get_user_profile

Get a seller's profile information.

Returns: username, rating, review breakdown, items listed/sold, location, member since, last active.

get_user_items

Browse all items listed by a specific user.

search_brands

Search for brand names and get their IDs for use in search filters.

Configuration

Supported Domains

Architecture

src/
  index.ts              # Entry point, stdio transport
  server.ts             # MCP server config & tool registration
  tools/
    search.ts           # search_items tool
    item.ts             # get_item_details tool
    user.ts             # get_user_profile tool
    user-items.ts       # get_user_items tool
    brands.ts           # search_brands tool
  api/
    client.ts           # HTTP client (session, cache, rate limit, retry)
    session-provider.ts # Browser-based session (Cloudflare bypass)
    browser-utils.ts    # Shared Puppeteer/stealth utilities
    types.ts            # Vinted API response types
  utils/
    cache.ts            # TTL cache with LRU eviction
    rate-limiter.ts     # Token bucket rate limiter
    mcp-error.ts        # Shared MCP error response builder

Reliability Features

• Rate limiting: Token bucket (10 req/10s) prevents API bans

• Caching: LRU cache (3min TTL, 200 entries max) reduces redundant requests

• Retry: Exponential backoff (1s, 2s) on 429/5xx errors

• Session recovery: Automatic cookie refresh on 401/403 with request coalescing

• Request deduplication: Concurrent identical requests share a single API call

• Cloudflare bypass: Puppeteer with stealth plugin for session acquisition

License

MIT