@theyahia/wildberries-mcp
This server exposes tools to manage a Wildberries seller account via the Seller API: products, prices, stocks, orders, sales, supplies, analytics, feedback, questions, returns, and advertising.
Products & Content: list product cards, get product details by nmIDs.
Prices: update product prices (async upload task).
Stocks: update or get FBS stock levels per warehouse.
Orders: get order lists (filtered by date/limit) and new/unprocessed orders.
Sales & Incomes: retrieve sales reports, FBW income deliveries, and FBW stock levels since a date.
Warehouses & FBS Supplies: list warehouses, create/get supplies, attach orders to a supply, close a supply for delivery, and retrieve supply barcode (QR).
Analytics: detailed sales report by period, ABC (Pareto) analysis, product sales funnel, and paid storage cost report.
Pricing Reference: get commission rates per category and box/logistics tariffs for a date.
Feedbacks & Questions: list/answer product feedbacks, list/reply to customer questions.
Returns: get buyer return claims (active or archived) with filters.
Advertising: get account balance, list campaigns by type/status, and get full campaign statistics over a date range.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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.
🗄 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-mcpis 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.
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 --httpClaude 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-mcpAuthentication & 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 |
|
Prices & discounts |
|
Marketplace |
|
Statistics |
|
Analytics |
|
Tariffs (Common) |
|
Feedbacks & questions |
|
Returns |
|
Advertising |
|
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 |
|
Prices & discounts |
|
Marketplace (FBS) |
|
Statistics |
|
Analytics |
|
Common / Tariffs |
|
Feedbacks & questions |
|
Returns |
|
Advertising |
|
Tools (30)
Products & content
Tool | Method | Host · Endpoint |
| POST | content · |
| POST | content · |
| POST | prices · |
| PUT | marketplace · |
| POST | marketplace · |
Orders & sales
Tool | Method | Host · Endpoint |
| GET | marketplace · |
| GET | marketplace · |
| GET | statistics · |
| GET | statistics · |
| GET | statistics · |
Warehouses & FBS supplies
Tool | Method | Host · Endpoint |
| GET | marketplace · |
| GET | marketplace · |
| POST | marketplace · |
| PATCH | marketplace · |
| PATCH | marketplace · |
| GET | marketplace · |
Analytics
Tool | Method | Host · Endpoint |
| GET | statistics · |
| GET | statistics · |
| POST | analytics · |
| GET | analytics · |
Pricing reference
Tool | Method | Host · Endpoint |
| GET | common · |
| GET | common · |
Feedbacks & questions
Tool | Method | Host · Endpoint |
| GET | feedbacks · |
| PATCH | feedbacks · |
| GET | feedbacks · |
| PATCH | feedbacks · |
Returns & ads
Tool | Method | Host · Endpoint |
| GET | returns · |
| GET | advert · |
| GET | advert · |
| POST | advert · |
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.
409penalty handling: readsX-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 |
| yes | Wildberries Seller API token (JWT). |
| no | Per-request timeout in ms (default 30000). |
| no | HTTP port when running with |
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 testLicense
MIT — see LICENSE.
Available Tools
30 toolsadd_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
Scored across 30 tools
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.
All tool names follow a consistent verb_noun pattern (e.g., list_campaigns, get_product, update_prices), with no mixed conventions or vague verbs.
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.
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
Unified MCP server for 70+ eCommerce platforms: products, orders, customers, and more.
Hosted MCP server for OTTO Market, Kaufland and Mirakl sellers: orders, stock, listings and ads.
MCP server for SkuVault — products, inventory, sales, purchase orders and stock adjustments.
Hosted Amazon Seller and Vendor MCP server for Claude, ChatGPT, Cursor, Codex, Gemini, Copilot.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceMCP server for Wildberries API that enables fetching product cards with multi-cabinet support, automatic pagination, and retry logic.1-
- FlicenseNot gradedqualityDmaintenanceMCP server that turns Wildberries marketplace into a toolkit for LLM agents, enabling product search, detailed card inspection, price history, reviews, and cross-product comparison.-
- AlicenseAqualityDmaintenanceMCP server for Wildberries Seller API enabling management of products, orders, supplies, analytics, advertising, and finance through natural language commands.32MIT
- AlicenseNot gradedqualityBmaintenanceMCP 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