Skip to main content
Glama
@theyahia/wildberries-mcp

@theyahia/wildberries-mcp

by theYahia

🗄 Repository archived

Development has moved to theYahia/WWmcp — a monorepo of MCP servers for non-Western APIs: CIS, MENA, Africa, LATAM, Southeast Asia. Shared core @theyahia/mcp-core, unified CI, unified release pipeline.

The current version of what was here: servers/wildberries/

The npm package is the same — @theyahia/wildberries-mcp, installs and works as before. Nothing is updated here anymore. Issues and pull requests — in WWmcp.

Archived — development moved to theYahia/WWmcp, a monorepo of MCP servers for non-Western APIs. The current version of this package now lives at servers/wildberries/. The npm package @theyahia/wildberries-mcp is unchanged. Please open issues and pull requests there.

@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

Related MCP server: wildberries-mcp

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.

Available Tools

30 tools
add_orders_to_supplyC

Attach one or more assembly orders to an FBS supply

Inputs: orderIds (required), supplyId (required).

create_supplyC

Create a new FBS supply (delivery)

Inputs: name (required).

deliver_supplyA

Close an FBS supply and send it to delivery (orders move to 'in delivery')

Inputs: supplyId (required).

get_abc_analysisB

Compute ABC analysis of products by sales revenue (Pareto). A = products making up the top 80% of revenue, B = next 15%, C = bottom 5%. Identifies best-sellers and slow movers.

Inputs: dateTo (required), dateFrom (required).

get_balanceA

Get advertising account balance (balance, net account, bonuses)

Inputs: no named parameters.

get_campaign_statsC

Get full advertising statistics for one or more campaigns over a date range

Inputs: dateTo (required), dateFrom (required), campaignIds (required).

get_commissionB

Get WB commission rates per category (subject)

Inputs: locale.

get_fbw_stocksA

Get FBW stock levels (goods stored at WB warehouses) since a date

Inputs: dateFrom (required).

get_feedbacksB

Get product feedbacks (reviews)

Inputs: skip, take, order, isAnswered.

get_funnelB

Get the product sales funnel (views, add-to-cart, orders, buyouts) by period

Inputs: dateTo (required), dateFrom (required), page, nmIDs.

get_incomesC

Get FBW supply incomes (deliveries to WB warehouses) since a date

Inputs: dateFrom (required).

get_new_ordersA

Get new (unprocessed) FBS orders

Inputs: no named parameters.

get_ordersC

Get FBS orders list with filters

Inputs: next, limit, dateTo, dateFrom.

get_paid_storageB

Get the paid storage cost report for a period (async report: created, polled, then downloaded)

Inputs: dateTo (required), dateFrom (required).

get_productB

Get detailed info for specific product cards by nm IDs

Inputs: nmIDs (required).

get_questionsB

Get customer questions about products

Inputs: skip, take, order, isAnswered.

get_returnsB

Get buyer return claims (requests to return goods)

Inputs: nmId, limit, offset, isArchive.

get_salesC

Get sales report

Inputs: dateFrom (required), flag, dateTo.

get_statisticsC

Get detailed realization (sales) report by period

Inputs: dateTo (required), dateFrom (required), limit, rrdid.

get_stocksB

Get current FBS stock levels for a specific warehouse

Inputs: warehouseId (required), skus.

get_supplyC

Get FBS supplies (deliveries) list with pagination

Inputs: next, limit.

get_supply_barcodeA

Get the QR barcode for an FBS supply (available after deliver_supply)

Inputs: supplyId (required), type.

get_tariffsB

Get WB box (logistics & storage) tariffs for a date

Inputs: date.

get_warehousesA

Get list of WB warehouses (offices)

Inputs: no named parameters.

list_campaignsA

List advertising campaigns grouped by type and status (counts + IDs)

Inputs: no named parameters.

list_productsA

List seller products (cards) with pagination and optional text search

Inputs: limit, cursor, textSearch.

reply_feedbackB

Post a reply to a customer review on Wildberries

Inputs: id (required), text (required).

reply_questionB

Post an answer to a customer question on Wildberries

Inputs: id (required), text (required), state.

update_pricesB

Update product prices (creates an async upload task)

Inputs: prices (required).

update_stocksB

Update FBS product stocks at a specific warehouse

Inputs: stocks (required), warehouseId (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 30 tools

    Disambiguation4/5

    Most tools are clearly distinct (e.g., get_orders vs get_new_orders), but some overlap exists between reporting tools like get_sales, get_statistics, and get_funnel; however, descriptions clarify differences.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (e.g., list_campaigns, get_product, update_prices), with no mixed conventions or vague verbs.

    Tool Count4/5

    30 tools is on the high side but appropriate given the breadth of Wildberries operations (advertising, products, orders, supplies, feedback, analytics). Each tool serves a specific need, though some consolidation could reduce count.

    Completeness3/5

    Covers most key areas but notable gaps exist: no create/update product card, no campaign management beyond stats/list. Core order and supply workflows are complete, but product lifecycle and advertising tools are missing update/delete operations.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server that turns Wildberries marketplace into a toolkit for LLM agents, enabling product search, detailed card inspection, price history, reviews, and cross-product comparison.
      -
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for Wildberries Seller API enabling management of products, orders, supplies, analytics, advertising, and finance through natural language commands.
      3
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server that simplifies interaction with Wildberries API, providing unified access to analytics, promotion statistics, sales funnel data, search queries, stock reports, and EVIRMA PRO report imports.
      MIT