Wildberries 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

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

Сервер отдаёт 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 за это время ничего не сломал. Обязательств по срокам нет.

Если исправление нужно срочно — напишите на d0371153@gmail.com. Issues и pull request'ы тоже приветствуются и разбираются.

Лицензия

MIT — см. LICENSE.