How do I use @theyahia/wildberries-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@@theyahia/wildberries-mcp list new orders" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

@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.

npm License: MIT

Quick Start

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:

{
  "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

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

Related MCP server: ozon-mcp

Authentication & token scopes

Authorization: Bearer {WB_API_TOKEN} (JWT, 180-day validity). Get your token in the seller portal 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

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

License

MIT — see LICENSE.

@theyahia/wildberries-mcp

@theyahia/wildberries-mcp

Quick Start

Claude Desktop

Smithery

Authentication & token scopes

Architecture — per-category hosts

Tools (30)

Products & content

Orders & sales

Warehouses & FBS supplies

Analytics

Pricing reference

Feedbacks & questions

Returns & ads

Rate limiting

Configuration

Demo prompts

Development

License

Maintenance

Resources

Latest Blog Posts

MCP directory API