WB MCP Server

WB MCP Server

Управляйте магазинами Wildberries из чата с ИИ-ассистентом.202 инструмента Seller API — карточки, цены, реклама, поставки, отзывы, финансы, аналитика —доступны Claude, Cursor, Copilot, Gemini CLI и любому другому MCP-клиенту.Для продавцов WB, у которых один или несколько кабинетов и нет желания кликать в личномкабинете то, что можно спросить словами.

Торгуете ещё и на Ozon? Есть такой же сервер для Ozon.

Сервер в ежедневной работе больше пяти месяцев, на порядка двадцати кабинетах WB,202 инструмента. Это личный рабочий инструмент автора, и обновляется он по мересобственной необходимости — как именно.

Ты: Какие мои карточки заблокированы и почему?
Ты: Покажи ДРР по всем кампаниям за неделю и выключи те, где он выше 15%.
Ты: На каких складах коэффициент приёмки сейчас 0 или 1?
Ты: Ответь на все новые отзывы с оценкой 5 благодарностью.

Что умеет

202 инструмента, сгруппированные по разделам Wildberries Seller API.Полный нумерованный список с описанием каждого — в docs/tools.md.

Три вещи, которых обычно нет у похожих серверов:

• Мульти-магазин. Каждый вызов принимает shop_id, поэтому два кабинета WB живутв одном диалоге. Если магазин один — shop_id можно не указывать.
• Диагностика WB API. Сервер сам пингует хосты WB, делает лёгкие пробные запросыпо каждой категории, разбирает срок действия и права токена и подсвечивает«деградации»: инструмент раньше работал, а теперь стабильно падает — верный признак,что WB изменил API.
• Шифрование токенов. Токены WB лежат зашифрованными (Fernet), а не в конфиге клиента.

Быстрый старт

Вариант 1: одна команда, без Docker

Сервер работает по stdio — так его подключают Claude Desktop, Cursor, VS Code идругие MCP-клиенты. Ничего собирать не нужно:

uvx wb-mcp-server

Или через pip:

pip install wb-mcp-server
wb-mcp

Конфигурация клиента (например, claude_desktop_config.json):

{
  "mcpServers": {
    "wildberries": {
      "command": "uvx",
      "args": ["wb-mcp-server"],
      "env": {
        "WB_API_TOKEN": "ваш токен Wildberries API",
        "DATA_DIR": "~/.wb-mcp"
      }
    }
  }
}

DATA_DIR укажите на любой доступный для записи каталог — там хранятся магазины,ключи и статистика. По умолчанию используется /data (путь для Docker).

Вариант 2: Docker с веб-интерфейсом

Нужен, если хотите дашборд, диагностику WB API и удобное добавление магазиновчерез браузер. Понадобится Docker (Docker Desktop или OrbStack) и токенWildberries Seller API.

git clone https://github.com/DeviceIngineering/wb-mcp-server.git
cd wb-mcp-server
cp .env.example .env          # для локального запуска можно оставить как есть
docker compose up -d --build

Проверка:

curl -s http://localhost:8001/api/health
# {"status":"ok","auth_enabled":false,"health_check_interval_min":30,...}

Что открылось:

Дальше:

1. Откройте http://localhost:8001/shops → Добавить магазин → вставьте токен WB → Проверить.Токен берётся в портале продавца: Настройки → Доступ к API → Создать токен(срок жизни 180 дней, остаток виден на странице диагностики).
2. Подключите MCP-клиент — см. следующий раздел.
3. Спросите ассистента: «покажи список моих магазинов на Wildberries» — должен сработатьинструмент wb_list_shops.

Разбор команды запуска:

Остановить: docker compose down (данные останутся в томе wb_data).Логи: docker compose logs -f.

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 указывать обязательно: по умолчанию сервер пишет в /data — путь внутри контейнера.

Установка в клиенты

Сервер отдаёт MCP по SSE: GET /sse — поток событий, POST /messages — сообщения клиента.Поддержка SSE у клиентов разная, поэтому под каждый есть отдельная инструкция —с путями к конфигу на macOS, Linux и Windows, готовым JSON и вариантами с токеном и без.

Общий обзор и таблица совместимости — docs/README.md.

Где у клиента есть команда, настраивающая подключение самостоятельно, инструкция начинаетсяс неё, а правка JSON идёт вторым способом. Самый короткий вариант — Claude Code:

claude mcp add --transport sse wildberries http://localhost:8001/sse
claude mcp list      # ожидается: wildberries ... ✔ Connected

Мульти-магазин и безопасность

Несколько кабинетов. Магазины добавляются на /shops, каждый получает свой shop_id.Инструмент wb_list_shops возвращает список; 200 из 202 инструментов принимают shop_idпервым параметром (исключения — wb_list_shops и wb_degradations).Если магазин один, параметр можно опустить: сервер подставит единственный доступный.

Смысл не в том, чтобы «уметь два аккаунта», а в том, что стратегия пишется один рази раскатывается на все кабинеты: правило по ценам, шаблон ответов на отзывы, потолокставки в рекламе применяются ко всем магазинам в одном диалоге — без переключенияаккаунтов и без раскладывания ключей по конфигам разных клиентов.Сколько кабинетов можно подключить. Ограничения в коде нет: shops.json — обычныйсловарь, добавляйте сколько угодно. Потолок задаёт не сервер, а Wildberries: всекабинеты ходят в WB с одного IP-адреса — того, где стоит этот сервер, — а лимитысчитаются в том числе по адресу. Оценка автора: порядка двух десятков кабинетов на одинадрес держатся в безопасной зоне. Дальше — разносить по нескольким серверам с разнымиадресами.

Почему это важнее, чем кажется, видно из лимитов WB:у ряда методов 3 запроса в минуту, а любой ответ 4XX засчитывается как 10 запросов.При десятке кабинетов на одном сервере несколько неверных запросов подряд съедают лимитв десять раз быстрее — и упрутся в него все магазины сразу, а не тот, где ошиблись.

Следить за этим есть чем:

• Фоновая диагностика шлёт по одному /ping на хост за прогон (лимит — 3 запросаза 30 секунд на хост) и складывает неудачные проверки и предупреждения в историю.Приближение к лимиту видно заранее, а не по факту блокировки.
• Детектор деградаций различает два случая: одновременная деградация многихинструментов — это троттлинг по адресу, деградация одного — сломался конкретныйэндпоинт WB. По дашборду это видно с одного взгляда.

Где лежат токены. В томе wb_data (внутри контейнера — /data):

• shops.json — магазины, токены зашифрованы Fernet;
• .encryption_key — ключ шифрования, генерируется при первом запуске;
• stats.db — SQLite со статистикой вызовов и историей диагностики.

Ключ лежит рядом с зашифрованными данными, поэтому шифрование защищает от случайнойутечки одного файла shops.json (бэкап, копипаста), но не от того, кто получил доступко всему тому. Переносить данные нужно томом целиком — см. DEPLOY.md.

Авторизация MCP. Переменная MCP_AUTH_TOKEN в .env:

openssl rand -hex 32   # значение вписать в .env → MCP_AUTH_TOKEN=
docker compose up -d

• пусто (по умолчанию) — /sse открыт всем, у кого есть сетевой доступ к порту;
• задан — клиент обязан передать Authorization: Bearer <токен> или ?token=<токен>в URL. Второй вариант выручает клиенты, которые не умеют произвольные заголовки.

Токен проверяется на обоих MCP-эндпоинтах — и на GET /sse, и на POST /messages.

Чего сервер не делает:

• Веб-интерфейс (/, /shops, /diagnostics) токеном не закрыт — он доступен всем,у кого есть сетевой доступ к порту.
• Порт 8001 не рассчитан на проброс в интернет. Для доступа извне — Tailscale или VPN.
• HTTPS сервер не терминирует. Нужен внешний доступ по TLS — ставьте reverse proxy.

Веб-интерфейс: видно каждый вызов

У обычного MCP-сервера вызовы уходят в никуда: что именно ассистент сделал, сколько этозаняло и что ответил маркетплейс — не видно, а о проблеме узнаёшь, когда что-тоне сработало. Здесь на каждый вызов есть запись, а на каждый магазин — состояние.Для инструмента, которым управляют реальными деньгами в магазине, это условие доверия,а не украшение. За пять месяцев ежедневной работы на двух десятках кабинетов эти страницыи накопили то, что перечислено в разделе про лимиты WB.

Дашборд — /

Скриншот — в начале страницы.

Сводка по всем вызовам инструментов (stats.get_summary()):

• всего вызовов, вызовов за сегодня, число ошибок, средняя длительность вызова;
• топ-10 инструментов: сколько раз вызван, среднее время, сколько ошибок;
• лента последних 50 вызовов: время, магазин, инструмент, длительность в миллисекундах,успех или ошибка, текст ошибки;
• фильтр по магазину — переключатель «Все / конкретный кабинет» над сводкой.

Магазины — /shops

Кабинеты добавляются и удаляются прямо в браузере, без правки файлов и перезапускаконтейнера. У каждого магазина есть кнопка «Проверить»: она делает лёгкий реальныйзапрос к WB и сразу говорит, живой ли токен, — а не оставляет выяснять это в моментпервого рабочего вызова. В списке токены показываются замаскированными (abc***xyz).

Токены шифруются Fernet и лежат в shops.json внутри тома с данными; ключ —в .encryption_key там же. Пул HTTP-клиентов сбрасывается при сохранении и удалениимагазина, так что новый токен подхватывается сразу.

Диагностика — /diagnostics

(на скриншоте — демо-магазин с вымышленным токеном: WB отвечает 401 на каждый pingи на каждую пробу, поэтому вся страница красная. Так и выглядит неудачная проверка —сервер при этом исправен. С рабочим токеном строка «Проверка …» показываетping 13/13, пробы 20/20, а статус магазина — «✅ Здоров».)

Фоновая проверка каждые HEALTH_CHECK_INTERVAL_MIN минут (по умолчанию 30), по каждомумагазину:

• токен — срок действия, категории доступа, флаги «только чтение» и «песочница»;
• ping 13 хостов WB API — доступность и задержка каждого;
• 20 проб — по одному лёгкому реальному GET на категорию API. Именно они ловятситуацию «эндпоинт отдаёт 404, потому что WB его переименовал»;
• предупреждения человеческим языком: «токен истекает через N дней»,«Контент: 404 на /content/v2/... — возможно, WB изменил API»;
• история проверок с автоматической ротацией (хранятся последние 1000 записей);
• кнопка «Проверить сейчас» — прогнать всё немедленно.

Детектор деградаций

Самое полезное, что даёт накопленная статистика. Сервер сам находит инструменты,которые раньше работали, а теперь стабильно падают: последние три вызова — ошибки,при этом успешные вызовы в истории были. По каждому такому инструменту показываютсявремя последнего успешного вызова, число подряд идущих ошибок, текст последней ошибкии момент, когда всё сломалось.

То есть сервер по собственной статистике обнаруживает, что Wildberries сломал илиотключил эндпоинт, — и говорит об этом до того, как вы упрётесь в это в работе.Рядом с разделом про лимиты и сроки отключения эндпоинтовэто его практическое продолжение: там перечислено то, что WB уже анонсировал,здесь — то, что он сделал молча.

Смотреть можно на дашборде или инструментом wb_degradations — прямо из чата.

JSON для внешнего мониторинга

Всё, что видно глазами, снимается и машиной:

Так что сервер можно повесить в Uptime Kuma, Zabbix или любой другой мониторинги узнавать о сломанном токене раньше, чем о нём расскажет ассистент.

Как это устроено

Один Docker-контейнер, внутри FastAPI-приложение, которое совмещает две роли:MCP-сервер по SSE и небольшой веб-интерфейс. По файлу на абзац:

• wb_mcp/server.py — сам MCP-сервер. Список TOOLS из 202 объектов Tool (имя,описание, JSON-схема аргументов) — это то, что клиент получает в ответ на tools/list.Вызовы разводятся тремя словарями: NO_CLIENT_DISPATCH (доступ к WB не нужен),CLIENT_DISPATCH (нужен HTTP-клиент магазина), SHOP_DISPATCH (нужен ещё и shop_id).Тут же живёт stdio-точка входа main() — на случай клиента, который умеет только stdio.
• wb_mcp/client.py — HTTP-клиенты 14 хостов Wildberries. Один WBClient на магазин,внутри httpx.AsyncClient с токеном; клиенты кэшируются в пуле по shop_id.
• wb_mcp/app.py — FastAPI: GET /sse и POST /messages для MCP, страницы дашборда,магазинов и диагностики, JSON-API /api/*, проверка MCP_AUTH_TOKEN, фоновый циклhealth-проверок.
• wb_mcp/settings.py — магазины и ключи: чтение и запись shops.json, шифрованиеFernet, миграция старого однокабинетного settings.json, маскирование токенов для UI.Есть fallback: если задана переменная WB_API_TOKEN, появляется магазин default.
• wb_mcp/diagnostics.py — ping хостов WB, декодер JWT-токена (срок, права, sandbox),«пробы» — по одному лёгкому реальному запросу на категорию API, новости WB.
• wb_mcp/stats.py — SQLite через aiosqlite: каждый вызов инструмента пишется с временем,успехом и shop_id; отсюда берутся детектор деградаций и история health-проверок.
• wb_mcp/templates/ — три страницы на PicoCSS, без сборки фронтенда.

Неочевидные места:

• shop_id подставляется сам, пока магазин один. Удобно в быту, но при добавлениивторого кабинета запросы без shop_id начнут возвращать «Укажите shop_id».
• В статистику пишется каждый вызов, включая упавшие. Отсюда работает детектордеградаций: «раньше работало, теперь стабильно падает» — сигнал изменения WB API,а не вашей ошибки. Смотреть: инструмент wb_degradations или дашборд.
• Фоновая диагностика раз в 30 минут делает реальные запросы к WB и расходует лимиты.Мешает — поставьте HEALTH_CHECK_INTERVAL_MIN=0 в .env.
• Ответы возвращаются как есть, сырым JSON от WB, без переупаковки. Инструменты от этогопредсказуемы, но крупные отчёты стоит запрашивать с фильтрами, иначе ответ съест контекст.
• POST /messages смонтирован как отдельное ASGI-приложение (Mount), а не какобычный маршрут FastAPI: handle_post_message сам отправляет ASGI-ответ, и внутримаршрута фреймворк отправлял бы его второй раз — соединение рвалось бы на каждом POST.Поэтому авторизация для этого эндпоинта проверяется вручную внутри приложения.
• Версия библиотеки mcp зафиксирована как >=1.0.0,<2. Сервер написан поддекораторное API mcp 1.x (@app.list_tools()), в mcp 2.0 его убрали. Не снимайтеверхнюю границу в pyproject.toml: с mcp 2.x сервер падает на стартес AttributeError: 'Server' object has no attribute 'list_tools'.

Переменные окружения

Ограничения Wildberries API

Это ограничения самого WB, а не сервера, — но ассистент будет натыкаться на них регулярно,и знать о них лучше заранее. Список собран не переписыванием справки: это пять месяцевежедневных вызовов на двух десятках кабинетов плюс журнал диагностики.

• GET /adv/v3/fullstats (статистика рекламы) — 3 запроса в минуту, период не больше 31 дня.
• Воронка продаж v3 — 3 запроса в минуту; история по дням доступна максимумза последнюю неделю.
• /ping — 3 запроса за 30 секунд на хост (фоновая диагностика это учитывает).
• Любой ответ 4XX засчитывается WB как 10 запросов к лимиту (правило с 04.06.2026).Один неверный параметр в цикле — и вы упёрлись в лимит.
• reportDetailByPeriod удаляется 15.07.2026; сервер уже ходит в finance-apiс fallback на старый эндпоинт.
• Создание поставок FBW через API невозможно — только в личном кабинете.Инструменты wb_fbw_* информационные.
• Токен WB живёт 180 дней. Остаток показывают wb_token_info и страница /diagnostics.
• Ответ 429 от WB — это лимит, а не поломка. Повторите через минуту.

Сверено с документацией dev.wildberries.ru по состоянию на июнь 2026.

Технический справочник

Хосты Wildberries Seller API

Диагностика

• Страница /diagnostics — по каждому магазину: срок действия токена и его права,ping всех хостов WB API, пробы по категориям, история проверок, кнопка «Проверить сейчас».
• Фоновая автопроверка каждые HEALTH_CHECK_INTERVAL_MIN минут.
• Детектор деградаций — подсвечивает на дашборде инструменты, которые перестали работать.
• MCP-инструменты: wb_diagnostics, wb_token_info, wb_degradations, wb_api_news.
• GET /api/health — JSON-сводка для мониторинга извне.
• POST /api/diagnostics/run — прогнать проверку всех магазинов прямо сейчас.
• GET /api/diagnostics/<shop_id> — полная диагностика одного магазина.

Структура проекта

wb-mcp-server/
├── docker-compose.yml          # порт 8001, том wb_data
├── Dockerfile                  # python:3.12-slim
├── pyproject.toml
├── DEPLOY.md                   # деплой на отдельную машину, перенос данных
├── docs/                       # подключение клиентов + справочник инструментов
└── wb_mcp/
    ├── server.py       # MCP-сервер: 202 инструмента, диспетчеризация, stdio-режим
    ├── client.py       # HTTP-клиенты 14 API Wildberries
    ├── app.py          # FastAPI: SSE + веб-интерфейс + авторизация + health-loop
    ├── diagnostics.py  # ping, JWT-декодер, пробы, новости API
    ├── settings.py     # магазины и ключи (Fernet)
    ├── stats.py        # статистика вызовов и история проверок (SQLite)
    └── templates/      # PicoCSS: dashboard, diagnostics, shops

Деплой

Вынести сервер на отдельную машину, перенести магазины, настроить автозапуск —см. DEPLOY.md.

Тот же сервер для Ozon

DeviceIngineering/ozon-mcp-server —тот же инструмент для другого маркетплейса: одна архитектура, тот же веб-интерфейсс дашбордом и диагностикой, та же мульти-магазинность через shop_id, тот же транспортSSE и те же способы подключения к клиентам. Разобрались с одним — второй запускаетсяпо той же инструкции; отличаются порт и набор инструментов.

Их можно держать одновременно на одной машине: порты разные, данные в разныхDocker-томах, конфликта нет.

Соседство на одном сервере не мешает и по лимитам: наружу оба ходят с одного IP,но Wildberries и Ozon считают лимиты каждый у себя — это разные площадки.Ограничение по числу кабинетов, о котором сказано в разделе про мульти-магазин,действует внутри каждой площадки отдельно.

Обновления и поддержка

Wildberries меняет API постоянно: эндпоинты добавляются, переименовываются и отключаются —в разделе про ограничения перечислено то, что уже поймано на практике.Этот сервер — рабочий инструмент автора: больше пяти месяцев ежедневной работына порядка двадцати кабинетах. Обновляется он по мере собственной необходимости:когда очередное изменение ломает что-то в его магазинах, а не по расписанию.Поэтому промежутки между коммитами бывают долгими — это значит, что WB за это времяничего не сломал. Обязательств по срокам нет.

Если исправление нужно срочно — напишите на [email protected].Issues и pull request'ы тоже приветствуются и разбираются.

Лицензия

MIT — см. LICENSE.