MCP 服务器

Wildberries API MCP Server

MCP 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.

README

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

Репозиторий: 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-ключа.

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

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

/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.
Создайте токен с необходимыми разрешениями.
Для аналитики и продвижения выдайте соответствующие права.
Сохраните токен безопасно: сервер не сохраняет его и принимает в заголовке 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.