Wb MCP Server

WB MCP Server

Run your Wildberries stores from a chat with an AI assistant. 197 tools covering the Wildberries Seller API — product cards, prices, ads, shipments, reviews, finance, analytics — exposed to Claude, Cursor, Copilot, Gemini CLI and any other MCP client. Built for WB sellers (Wildberries is Russia's largest marketplace) who run one or several seller accounts and would rather ask a question than click through the seller portal.

Selling on Ozon too? There is the same server for Ozon.

The server has been in daily use for more than five months across roughly twenty WB seller accounts, with 197 tools. It is the author's own working tool and is updated as the author needs it — details here.

You: Which of my product cards are blocked, and why?

You: Show ad cost share for every campaign this week and pause the ones above 15%. You: Which warehouses currently have an intake coefficient of 0 or 1? You: Reply to every new 5-star review with a thank-you note.

What it can do

197 tools, grouped by Wildberries Seller API area. The full numbered list with a description of each one is in [docs/tools.md](docs/tools.md).

Three things similar servers usually do not have:

• Multi-store. Every call takes a shop_id, so two WB seller accounts live in one conversation. With a single store you can omit shop_id entirely.
• WB API diagnostics. The server pings WB hosts by itself, sends one cheap probe request per API category, decodes the token's expiry and scopes, and highlights "degradations": a tool that used to work and now fails consistently — a reliable sign that WB changed the API.
• Encrypted tokens. WB tokens are stored encrypted (Fernet), not in your client's config.

Quick start

Option 1: one command, no Docker

The server speaks stdio, which is how Claude Desktop, Cursor, VS Code and other MCP clients connect to it. Nothing to build:

uvx wb-mcp-server

Or via pip:

pip install wb-mcp-server

wb-mcp

Client configuration (for example claude_desktop_config.json):

{

"mcpServers": { "wildberries": { "command": "uvx", "args": ["wb-mcp-server"], "env": { "WB_API_TOKEN": "your Wildberries API token", "DATA_DIR": "~/.wb-mcp" } } } }

Point DATA_DIR at any writable directory — it holds stores, keys and statistics. The default is /data, which is the path used inside Docker.

Option 2: Docker with the web dashboard

Use this if you want the dashboard, WB API diagnostics and browser-based store management. You need Docker (Docker Desktop or OrbStack) and a Wildberries Seller API token.

git clone https://github.com/DeviceIngineering/wb-mcp-server.git

cd wb-mcp-server cp .env.example .env # fine as-is for a local run docker compose up -d --build

Check:

curl -s http://localhost:8001/api/health

{"status":"ok","auth_enabled":false,"health_check_interval_min":30,...}

What you now have:

Next:

1. Open http://localhost:8001/shops → Добавить магазин (Add store) → paste the WB token → Проверить (Test). The token comes from the WB Seller Portal (seller.wildberries.ru): Настройки → Доступ к API → Создать токен (Settings → API access → Create token). It is valid for 180 days; the remaining lifetime is shown on the diagnostics page.
2. Connect an MCP client — see the next section.
3. Ask your assistant: "list my Wildberries stores" — the wb_list_shops tool should fire.

The start command, flag by flag:

Stop it with docker compose down (data stays in the wb_data volume). Logs: docker compose logs -f.

Running without Docker

git clone https://github.com/DeviceIngineering/wb-mcp-server.git

cd wb-mcp-server python3 -m venv .venv && source .venv/bin/activate pip install . DATA_DIR=./data PORT=8001 python -m wb_mcp.app

DATA_DIR is mandatory here: by default the server writes to /data, a path that only exists inside the container.

Installing into clients

The server speaks MCP over SSE: GET /sse is the event stream, POST /messages carries the client's messages. SSE support differs from client to client, so each one has its own guide — with config paths for macOS, Linux and Windows, ready-to-paste JSON, and variants with and without an auth token.

The per-client guides in docs/ are currently in Russian only. The configuration

in them is ready-made JSON with file paths and flags, which is readable regardless

of language.

Overview and compatibility table: docs/README.md.

Where a client has a command that configures the connection by itself, the guide starts with that command and treats editing JSON as the second option. The shortest setup of all — Claude Code:

claude mcp add --transport sse wildberries http://localhost:8001/sse

claude mcp list # expected: wildberries ... ✔ Connected

Multi-store and security

Several seller accounts. Stores are added on /shops; each one gets its own shop_id. wb_list_shops returns the list, and 200 of the 197 tools take shop_id as their first parameter (the exceptions are wb_list_shops and wb_degradations). With a single store the parameter can be omitted — the server substitutes the only one available.

The point is not "it supports two accounts" but that a strategy is written once and rolled out to every account: a pricing rule, a review-reply template, an advertising bid ceiling apply to all stores inside one conversation — no account switching, no scattering API keys across different clients' configs.

How many accounts you can connect. There is no limit in the code: shops.json is a plain dictionary, add as many as you like. The ceiling is set by Wildberries, not by this server: all accounts reach WB from a single IP address — the one running this server — and rate limits are counted per address as well. The author's own estimate: around twenty accounts per address stay in the safe zone. Beyond that, split them across several servers with different addresses.

Why this matters more than it looks — see the WB limits: several methods allow 3 requests per minute, and any 4XX response counts as 10 requests. With a dozen accounts on one server, a handful of malformed requests in a row burns the quota ten times faster — and every store hits the wall at once, not just the one that erred.

There are ways to watch for it:

• Background diagnostics send one /ping per host per run (the limit is 3 requests per 30 seconds per host) and record failed checks and warnings into a history. You see the limit approaching in advance, instead of learning about it from a block.
• The degradation detector tells two cases apart: many tools degrading at once means per-addr