@Theyahia/Wildberries

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

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.