# Wildberries Mcp

> MCP server for Wildberries — marketplace orders, analytics, stock (Russia). Part of WWmcp — 114 MCP servers for emerging markets.

- **Type:** MCP server
- **Install:** `agentstack add mcp-theyahia-wildberries-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [theYahia](https://agentstack.voostack.com/s/theyahia)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [theYahia](https://github.com/theYahia)
- **Source:** https://github.com/theYahia/wildberries-mcp

## Install

```sh
agentstack add mcp-theyahia-wildberries-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# @theyahia/wildberries-mcp

MCP server for the **Wildberries** Seller API — **30 tools** across products, prices, stocks, orders, sales, FBS supplies, analytics, feedbacks, questions, returns, and ads. Per-category host routing with rate limiting and 409 penalty protection. Stdio + Streamable HTTP transports.

[](https://www.npmjs.com/package/@theyahia/wildberries-mcp)
[](https://opensource.org/licenses/MIT)

## Quick Start

```bash
npm install -g @theyahia/wildberries-mcp

# stdio transport (for Claude Desktop, Cursor, etc.)
WB_API_TOKEN=your_token wildberries-mcp

# Streamable HTTP transport
WB_API_TOKEN=your_token wildberries-mcp --http
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "wildberries": {
      "command": "npx",
      "args": ["-y", "@theyahia/wildberries-mcp"],
      "env": { "WB_API_TOKEN": "your_token_here" }
    }
  }
}
```

Cursor / Windsurf / VS Code (Copilot) use the same `mcpServers` block in their MCP settings.

### Smithery

```bash
npx @smithery/cli install @theyahia/wildberries-mcp
```

## Authentication & token scopes

`Authorization: Bearer {WB_API_TOKEN}` (JWT, 180-day validity). Get your token in the
[seller portal](https://seller.wildberries.ru/supplier-settings/access-to-api) under
**Settings → Access to API**.

A single token can carry multiple **category scopes**. Because each tool talks to a
different API host, a token missing a scope returns `401` from *that* host while other
tools keep working. Enable the scopes you need:

| Scope | Powers tools |
|-------|--------------|
| Content | `list_products`, `get_product` |
| Prices & discounts | `update_prices` |
| Marketplace | `update_stocks`, `get_stocks`, `get_orders`, `get_new_orders`, `get_warehouses`, `get_supply`, `create_supply`, `add_orders_to_supply`, `deliver_supply`, `get_supply_barcode` |
| Statistics | `get_sales`, `get_incomes`, `get_fbw_stocks`, `get_statistics`, `get_abc_analysis` |
| Analytics | `get_funnel`, `get_paid_storage` |
| Tariffs (Common) | `get_commission`, `get_tariffs` |
| Feedbacks & questions | `get_feedbacks`, `reply_feedback`, `get_questions`, `reply_question` |
| Returns | `get_returns` |
| Advertising | `get_balance`, `list_campaigns`, `get_campaign_stats` |

When a call fails, the error message names the host and includes WB's `requestId`, so a
missing scope or wrong-host issue is obvious (e.g. `WB API GET advert-api.wildberries.ru/adv/v1/balance → 401: ...`).

## Architecture — per-category hosts

The Wildberries Seller API is **not** a single gateway. `seller.wildberries.ru` is the web
cabinet; the API is split across category hosts. Every request is routed to the right one:

| Category | Host |
|----------|------|
| Content | `content-api.wildberries.ru` |
| Prices & discounts | `discounts-prices-api.wildberries.ru` |
| Marketplace (FBS) | `marketplace-api.wildberries.ru` |
| Statistics | `statistics-api.wildberries.ru` |
| Analytics | `seller-analytics-api.wildberries.ru` |
| Common / Tariffs | `common-api.wildberries.ru` |
| Feedbacks & questions | `feedbacks-api.wildberries.ru` |
| Returns | `returns-api.wildberries.ru` |
| Advertising | `advert-api.wildberries.ru` |

## Tools (30)

### Products & content
| Tool | Method | Host · Endpoint |
|------|--------|-----------------|
| `list_products` | POST | content · `/content/v2/get/cards/list` |
| `get_product` | POST | content · `/content/v2/get/cards/detail` |
| `update_prices` | POST | prices · `/api/v2/upload/task` |
| `update_stocks` | PUT | marketplace · `/api/v3/stocks/{warehouseId}` |
| `get_stocks` | POST | marketplace · `/api/v3/stocks/{warehouseId}` |

### Orders & sales
| Tool | Method | Host · Endpoint |
|------|--------|-----------------|
| `get_orders` | GET | marketplace · `/api/v3/orders` |
| `get_new_orders` | GET | marketplace · `/api/v3/orders/new` |
| `get_sales` | GET | statistics · `/api/v1/supplier/sales` |
| `get_incomes` | GET | statistics · `/api/v1/supplier/incomes` |
| `get_fbw_stocks` | GET | statistics · `/api/v1/supplier/stocks` |

### Warehouses & FBS supplies
| Tool | Method | Host · Endpoint |
|------|--------|-----------------|
| `get_warehouses` | GET | marketplace · `/api/v3/offices` |
| `get_supply` | GET | marketplace · `/api/v3/supplies` |
| `create_supply` | POST | marketplace · `/api/v3/supplies` |
| `add_orders_to_supply` | PATCH | marketplace · `/api/v3/supplies/{id}/orders/{orderId}` |
| `deliver_supply` | PATCH | marketplace · `/api/v3/supplies/{id}/deliver` |
| `get_supply_barcode` | GET | marketplace · `/api/v3/supplies/{id}/barcode` |

### Analytics
| Tool | Method | Host · Endpoint |
|------|--------|-----------------|
| `get_statistics` | GET | statistics · `/api/v5/supplier/reportDetailByPeriod` |
| `get_abc_analysis` | GET | statistics · `reportDetailByPeriod` (computed Pareto) |
| `get_funnel` | POST | analytics · `/api/v2/nm-report/detail` |
| `get_paid_storage` | GET | analytics · `/api/v1/paid_storage` (async report) |

### Pricing reference
| Tool | Method | Host · Endpoint |
|------|--------|-----------------|
| `get_commission` | GET | common · `/api/v1/tariffs/commission` |
| `get_tariffs` | GET | common · `/api/v1/tariffs/box` |

### Feedbacks & questions
| Tool | Method | Host · Endpoint |
|------|--------|-----------------|
| `get_feedbacks` | GET | feedbacks · `/api/v1/feedbacks` |
| `reply_feedback` | PATCH | feedbacks · `/api/v1/feedbacks` |
| `get_questions` | GET | feedbacks · `/api/v1/questions` |
| `reply_question` | PATCH | feedbacks · `/api/v1/questions` |

### Returns & ads
| Tool | Method | Host · Endpoint |
|------|--------|-----------------|
| `get_returns` | GET | returns · `/api/v1/claims` |
| `get_balance` | GET | advert · `/adv/v1/balance` |
| `list_campaigns` | GET | advert · `/adv/v1/promotion/count` |
| `get_campaign_stats` | POST | advert · `/adv/v2/fullstats` |

## Rate limiting

Wildberries meters requests **per API category**, not as one global pool — and returns
`409` as a penalty for bursts. The client keeps one token-bucket limiter **per host** plus
finer buckets for the strictest endpoints:

- Per-host token buckets with a minimum interval between requests.
- `409` penalty handling: reads `X-Ratelimit-Retry-After` / `X-Ratelimit-Remaining`,
  deducts penalty tokens, and waits the indicated duration before retrying — penalties stay
  isolated to the offending category.
- Strict per-endpoint caps (paid-storage create/download 1/min, status 1/5s; prices ~10/6s).

The defaults are deliberately conservative and safe to raise once you've observed your
account's real limits. No configuration needed.

## Configuration

| Variable | Required | Description |
|----------|----------|-------------|
| `WB_API_TOKEN` | yes | Wildberries Seller API token (JWT). |
| `WB_TIMEOUT_MS` | no | Per-request timeout in ms (default 30000). |
| `PORT` | no | HTTP port when running with `--http` (default 3000). |

HTTP endpoints (`--http`): `POST /mcp` (requests), `GET /health` (`{ status, version, tools }`).

## Demo prompts

> "List the first 50 products in my catalog with current prices."
> "Run an ABC analysis for the last 30 days — which products make 80% of revenue?"
> "Create an FBS supply 'Morning 2026-06-23', attach orders 1001 and 1002, then close it for delivery and get its barcode."
> "Show unanswered questions and draft a reply to the first one."
> "What's my advertising balance and which campaigns are active?"

## Development

```bash
git clone https://github.com/theYahia/wildberries-mcp.git
cd wildberries-mcp
npm install
npm run build
npm test
```

## License

MIT — see [LICENSE](./LICENSE).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [theYahia](https://github.com/theYahia)
- **Source:** [theYahia/wildberries-mcp](https://github.com/theYahia/wildberries-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-theyahia-wildberries-mcp
- Seller: https://agentstack.voostack.com/s/theyahia
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.