Руководство по использованию Wildberries API MCP сервера

Docker publish

Репозиторий: https://github.com/antondrpq/Wildberries-API-MCP-Server

Содержание

Введение

Wildberries API MCP сервер представляет собой промежуточный сервис, который упрощает взаимодействие с API Wildberries. Он предоставляет унифицированный HTTP-интерфейс для аналитики, статистики продвижения, работы с остатками, CSV-отчётами и импорта данных EVIRMA PRO.

MCP сервер выполняет следующие функции:

упрощает обращение к различным эндпоинтам API Wildberries;
централизованно передаёт api-key клиента в Authorization при обращении к WB;
обрабатывает ошибки API и ограничения частоты запросов;
сохраняет совместимость локальных маршрутов при миграции WB API;
унифицирует обработку ответов;
принимает и нормализует выгрузки EVIRMA PRO.

Установка и запуск

Необходимые предварительные требования

Node.js 20 или выше;
npm;
Docker и Docker Compose (опционально, для контейнеризации);
токен API Wildberries с необходимыми разрешениями.

Способ 1: Прямая установка через Node.js

git clone https://github.com/antondrpq/Wildberries-API-MCP-Server.git
cd Wildberries-API-MCP-Server
npm install
npm start

Сервер запустится на порту 3000 по умолчанию.

Можно указать другой порт:

PORT=8080 npm start

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

Скопируйте .env.example в .env и при необходимости отредактируйте:

cp .env.example .env

Переменная	По умолчанию	Описание
`PORT`	`3000`	Порт HTTP-сервера
`NODE_ENV`	`production`	`production` / `development` / `test`
`RATE_LIMIT_MAX`	`100`	Максимум входящих запросов с одного IP в минуту

Тесты и линтер

npm test
npm run lint

Локально проект проверяется через Jest + Supertest и ESLint.

Способ 2: Использование Docker

docker build -t wb-api-mcp-server .
docker run -p 3000:3000 -d --name wb-api-mcp wb-api-mcp-server

Проверка:

curl http://localhost:3000/health

Ожидаемый ответ:

{
  "status": "ok",
  "timestamp": "2026-08-19T..."
}

Способ 3: Использование Docker Compose

cp .env.example .env
docker-compose up -d
docker-compose down

Способ 4: Готовый образ из GitHub Container Registry

Актуальный образ публикуется в GHCR:

docker pull ghcr.io/antondrpq/wildberries-api-mcp-server:latest
docker run -p 3000:3000 -d --name wb-api-mcp ghcr.io/antondrpq/wildberries-api-mcp-server:latest

Проверка:

curl http://localhost:3000/health

Доступные инструменты API

Сервер предоставляет следующие группы эндпоинтов.

1. Статистика продвижения

Поисковые кластеры рекламы

POST /api/adv/normquery/stats — статистика поисковых кластеров через WB POST /adv/v0/normquery/stats.
POST /api/adv/normquery/stats-v1 — статистика поисковых кластеров с детализацией через WB POST /adv/v1/normquery/stats.

Статистика рекламных кампаний

GET /api/adv/fullstats — статистика рекламных кампаний через WB GET /adv/v3/fullstats.
POST /api/adv/stats — статистика медийных кампаний через WB POST /adv/v1/stats.

Устаревающие методы

Следующие локальные маршруты сохранены для совместимости, но требуют отдельной проверки актуальных методов WB API:

GET /api/adv/auto/stat-words
GET /api/adv/stat/words
GET /api/adv/stats/keywords

2. Воронка продаж (Sales Funnel)

Локальные маршруты сохранены для обратной совместимости, но внутри используют актуальный WB Analytics v3:

POST /api/nm-report/detail → POST /api/analytics/v3/sales-funnel/products
POST /api/nm-report/detail/history → POST /api/analytics/v3/sales-funnel/products/history
POST /api/nm-report/grouped/history → POST /api/analytics/v3/sales-funnel/grouped/history

Сервер умеет преобразовывать legacy-поля старого формата (period, nmIDs, objectIDs, tagIDs) в формат v3 (selectedPeriod, nmIds, subjectIds, tagIds и другие).

3. Поисковые запросы

Текущая реализация использует WB Analytics v2:

POST /api/search-report/report — основной отчёт по поисковым запросам.
POST /api/search-report/table/groups — пагинация по группам поисковых запросов.
POST /api/search-report/table/details — пагинация по товарам внутри группы.
POST /api/search-report/product/search-texts — поисковые тексты конкретного товара.
POST /api/search-report/product/orders — заказы и позиции по поисковым текстам товара.

Пример основного отчёта:

const searchReport = await fetchFromMcp('/api/search-report/report', 'POST', {
  currentPeriod: {
    start: '2026-08-12',
    end: '2026-08-18'
  },
  positionCluster: 'all',
  orderBy: {
    field: 'avgPosition',
    mode: 'desc'
  },
  limit: 100,
  offset: 0
});

4. Отчёт по остаткам (Stocks Report)

Текущая реализация использует WB Analytics v2:

POST /api/stocks-report/products/groups
POST /api/stocks-report/products/products
POST /api/stocks-report/products/sizes
POST /api/stocks-report/offices

Пример:

const stocksReport = await fetchFromMcp('/api/stocks-report/products/products', 'POST', {
  nmIDs: [178773045],
  currentPeriod: {
    start: '2026-08-12',
    end: '2026-08-18'
  },
  stockType: '',
  skipDeletedNm: true,
  orderBy: {
    field: 'avgOrders',
    mode: 'desc'
  },
  offset: 0
});

5. CSV-отчёты продавца (Seller Analytics CSV)

POST /api/nm-report/downloads — создание CSV-отчёта.
GET /api/nm-report/downloads — получение списка отчётов.
POST /api/nm-report/downloads/retry — повторная генерация отчёта.
GET /api/nm-report/downloads/file/:downloadId — скачивание ZIP-файла отчёта.

6. Импорт данных EVIRMA PRO

POST /api/evirma/import/keywords-report — импорт XLS/XLSX-отчёта «Статистика РК по ключевым фразам».
POST /api/evirma/import/daily-zone-stats — импорт XLS/XLSX-отчёта «Статистика РК по дням и зонам показов».

EVIRMA PRO не предоставляет публичного API; сервер обрабатывает вручную экспортированные файлы.

7. Healthcheck

GET /health — проверка работоспособности сервера без API-ключа.

MCP-агенты

Помимо REST-эндпоинтов выше, сервер также отдаёт MCP Streamable HTTP эндпоинт (POST /mcp) с 32 инструментами, сгруппированными в четыре функциональных агента:

Финансист — баланс, отчёты реализации, эквайринг, готовый P&L одним вызовом (wb_finance_summary).
Реклама — кампании, баланс кабинета продвижения, бюджеты, ставки, агрегированная сводка (wb_ads_summary).
Ответы покупателям — отзывы, вопросы, чаты с покупателями (чтение и ответ).
Управляющий магазина — тарифы, FBS-заказы, сводка «здоровья бизнеса» (wb_business_summary).

Часть инструментов — WRITE (публикуют текст, видимый покупателю) или WRITE / DESTRUCTIVE (например, отмена заказа); полный список с пометками и требуемыми категориями токена — в MCP.md.

Права на write-инструменты определяются токеном WB, а не этим сервером. Сервер не фильтрует tools/list и не проверяет права заранее — он просто проксирует вызов с заголовком Authorization: <WB_API_KEY>. Если WB_API_KEY выпущен с флагом «Только чтение», Wildberries сам отклонит любой write-вызов (12 из 32 инструментов) с HTTP 403 — MCP-клиент увидит эти инструменты в tools/list, но выполнить их не сможет. Подробности и рекомендации по выпуску токена — в разделе «Token permissions and read-only mode» файла MCP.md.

Это отдельный протокол поверх того же порта, не подмножество REST API из раздела выше — предназначен для подключения к MCP-клиентам (например, Claude) как единый набор инструментов, а не для прямых HTTP-вызовов из своего кода.

Подробности: конфигурация, полный список всех 32 инструментов с описаниями, известные лимиты частоты запросов WB и пример smoke-теста через PowerShell — см. MCP.md.

Примеры использования

Получение статистики рекламных кампаний

/api/adv/fullstats — локальный GET-маршрут, который проксирует актуальный WB GET /adv/v3/fullstats.

const params = new URLSearchParams({
  ids: '1234567',
  beginDate: '2026-08-12',
  endDate: '2026-08-18'
});

const response = await fetch(
  `http://localhost:3000/api/adv/fullstats?${params.toString()}`,
  {
    headers: {
      'api-key': 'ВАШ_ТОКЕН_WILDBERRIES_API'
    }
  }
);

const data = await response.json();
console.log(data);

Параметры конкретного запроса должны соответствовать текущей схеме WB GET /adv/v3/fullstats.

Статистика поисковых кластеров рекламы

Для v0 и v1 используются разные имена полей.

Пример v0:

const response = await fetch('http://localhost:3000/api/adv/normquery/stats', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'api-key': 'ВАШ_ТОКЕН_WILDBERRIES_API'
  },
  body: JSON.stringify({
    from: '2026-08-12',
    to: '2026-08-18',
    items: [
      {
        advert_id: 1234567,
        nm_id: 178773045
      }
    ]
  })
});

Пример v1:

const response = await fetch('http://localhost:3000/api/adv/normquery/stats-v1', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'api-key': 'ВАШ_ТОКЕН_WILDBERRIES_API'
  },
  body: JSON.stringify({
    from: '2026-08-12',
    to: '2026-08-18',
    items: [
      {
        advertId: 1234567,
        nmId: 178773045
      }
    ]
  })
});

Получение статистики карточки товара

Сервер сохраняет привычный локальный маршрут, но внутри использует Sales Funnel v3:

const response = await fetch('http://localhost:3000/api/nm-report/detail', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'api-key': 'ВАШ_ТОКЕН_WILDBERRIES_API'
  },
  body: JSON.stringify({
    nmIDs: [178773045],
    period: {
      begin: '2026-08-12',
      end: '2026-08-18'
    }
  })
});

const data = await response.json();
console.log(data);

Анализ поисковой видимости

const searchReport = await fetch('http://localhost:3000/api/search-report/report', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'api-key': 'ВАШ_ТОКЕН_WILDBERRIES_API'
  },
  body: JSON.stringify({
    currentPeriod: {
      start: '2026-08-12',
      end: '2026-08-18'
    },
    positionCluster: 'all',
    orderBy: {
      field: 'avgPosition',
      mode: 'desc'
    },
    limit: 100,
    offset: 0
  })
});

const data = await searchReport.json();
console.log(data);

Поисковые тексты товара

const searchTexts = await fetchFromMcp('/api/search-report/product/search-texts', 'POST', {
  currentPeriod: {
    start: '2026-08-12',
    end: '2026-08-18'
  },
  nmIds: [178773045],
  topOrderBy: 'openCard',
  limit: 20
});

Управление запасами

const stocksReport = await fetchFromMcp('/api/stocks-report/products/products', 'POST', {
  nmIDs: [178773045],
  currentPeriod: {
    start: '2026-08-12',
    end: '2026-08-18'
  },
  stockType: '',
  skipDeletedNm: true,
  orderBy: {
    field: 'avgOrders',
    mode: 'desc'
  },
  offset: 0
});

Импорт отчёта EVIRMA PRO

curl -X POST http://localhost:3000/api/evirma/import/keywords-report \
  -H "api-key: ВАШ_ТОКЕН_WILDBERRIES_API" \
  -F "file=@Экспорт_..._cmp-advert-keywords-stats_....xlsx"

Размер файла ограничен 15 МБ. Поддерживаются .xlsx и .xls.

Типичные сценарии использования

1. Мониторинг эффективности рекламных кампаний

Получать статистику рекламных кампаний через /api/adv/fullstats.
Получать поисковые кластеры рекламы через /api/adv/normquery/stats или /api/adv/normquery/stats-v1.
Сохранять результаты в БД для исторического анализа.
Сравнивать показы, клики, расходы, корзины и заказы.

2. Анализ воронки продаж товаров

/api/nm-report/detail — детальная воронка по товарам.
/api/nm-report/detail/history — динамика по дням.
/api/nm-report/grouped/history — агрегированные данные по брендам, предметам и тегам.
Выявлять товары с низкими конверсиями и анализировать этапы просмотра → корзина → заказ → выкуп.

3. Оптимизация поисковой видимости

Используйте:

/api/search-report/report;
/api/search-report/table/groups;
/api/search-report/table/details;
/api/search-report/product/search-texts;
/api/search-report/product/orders.

Это позволяет анализировать позиции, поисковые фразы, переходы и заказы.

4. Управление запасами

Используйте stocks-report для оценки:

текущих остатков;
средних заказов;
скорости продаж;
распределения по складам;
потенциального времени покрытия запасами.

5. Генерация расширенных CSV-отчётов

Рекомендуемая последовательность:

POST /api/nm-report/downloads
        ↓
GET /api/nm-report/downloads
        ↓
POST /api/nm-report/downloads/retry  (если FAILED)
        ↓
GET /api/nm-report/downloads/file/:downloadId

Получение токена API

Войдите в личный кабинет продавца Wildberries.
Откройте раздел управления API.
Создайте токен с необходимыми разрешениями.
Для аналитики и продвижения выдайте соответствующие права.
Если сервер (в т.ч. MCP-агент) будет только читать данные — включите опцию «Только чтение». WB физически откажет любому write-запросу с таким токеном (HTTP 403), независимо от того, какие категории ему выданы. Для MCP это значит, что 12 write-инструментов (wb_feedback_answer, wb_order_cancel и другие — полный список в MCP.md) вернут ошибку 403, даже если MCP-клиент их вызовет: tools/list их всё равно покажет, но выполнить их через read-only токен нельзя. Это самый надёжный способ ограничить действия ИИ-агента — сильнее любой логики на стороне этого сервера.
Если какому-то сценарию действительно нужна запись (например, отдельный агент для отмены заказов) — выпустите под него отдельный токен без флага «Только чтение», а не снимайте этот флаг с общего аналитического токена.
Сохраните токен безопасно: сервер не сохраняет его и принимает в заголовке api-key на каждый запрос.

Устранение неполадок

`401 Unauthorized`

Проверьте наличие заголовка:

api-key: ВАШ_ТОКЕН_WILDBERRIES_API

`400 Bad Request`

Проверьте структуру body и обязательные поля конкретного WB endpoint.

`429 Too Many Requests`

Сервер возвращает 429. Если Wildberries передаёт заголовок X-RateLimit-Retry, сервер:

возвращает его клиенту как HTTP-заголовок X-RateLimit-Retry;
добавляет его значение в details.retryAfter.