# wildberries-mcp

An [MCP](https://modelcontextprotocol.io) server that turns Wildberries (the largest Russian marketplace) into a toolkit for LLM agents. It lets a model search products, inspect a product card, read its price history and reviews, and compare several products side by side — i.e. do **cross-product research**, which Wildberries' own built-in review AI (single-product only) does not do.

## Tools

| Tool | What it does |
|------|--------------|
| `search_products(query, limit)` | Search by keyword → article, name, brand, price, rating, review count |
| `get_product(article)` | Full card: name, brand, category, description, current price, rating |
| `get_price_history(article)` | Price points over time → reason about trends and real discounts |
| `get_reviews(article, limit)` | Aggregate rating, star distribution, review counts, sample review texts |
| `compare_products([articles])` | Side-by-side comparison of several products |

## How it works (the interesting part)

Wildberries has no public API for this, so the server talks to the same internal endpoints the website uses — which took some reverse-engineering, because they moved:

- **Product data** comes from the basket CDN: `basket-XX.wbbasket.ru/volA/partB/{article}/info/ru/card.json`. The `XX` host isn't fixed — it's derived from the article and the mapping changes as WB adds shards, so the client **probes and caches** the right host per volume instead of hardcoding a table.
- **Price history** lives next to it: `.../info/price-history.json`.
- **Reviews** are keyed by `imt_id` (not the article), so the client reads `imt_id` from the card, resolves the feedback host via `feedback-bt.wildberries.ru`, then fetches `feedbacks/v2/{imt_id}`.
- **Search** goes through `search.wb.ru/exactmatch/ru/common/v9/search`. It is aggressively **rate-limited** (HTTP 429), so all requests share a session, keep a minimum interval, and retry with exponential backoff.

The older endpoints most public WB scrapers use (`card.wb.ru/cards/v1`, feedbacks-by-article) are dead as of 2026; this uses the current ones.

## Setup

```bash
git clone https://github.com/shndo1337/wildberries-mcp.git
cd wildberries-mcp

python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # Linux/Mac

pip install -r requirements.txt
python server.py             # runs an MCP server over stdio
```

## Use it with Claude / any MCP client

Add to your MCP client config (e.g. Claude Desktop `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "wildberries": {
      "command": "python",
      "args": ["C:/path/to/wildberries-mcp/server.py"]
    }
  }
}
```

Then ask the agent things like *"Find wireless earbuds under 2000₽ with rating above 4.5 and compare the top 3 by reviews and price trend."*

## Example (`get_product`)

```json
{
  "article": 762015089,
  "name": "Наушники беспроводные A.Pods PRO 2 для iPhone и Android",
  "brand": "world of sound",
  "category": "Наушники беспроводные",
  "current_price_rub": 945.97,
  "rating": "4.6",
  "review_count": 125270
}
```

## Limitations

- Relies on Wildberries' internal endpoints — a change on their side can break tools; the code is structured so each source is isolated and easy to fix.
- Search is rate-limited by WB; heavy use needs the built-in backoff (already included) or proxies.
- No authentication / seller API — this is read-only public product data.