de en es ja ko ru zh

Wildberries API MCP Server

Name: Wildberries API MCP Server
Author: antondrpq

by antondrpq

Overview Schema Related Servers Score Discussions

JavaScript

Remote

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

Docker publish

Замените ВАШ_ЛОГИН в бейджах выше на имя вашего аккаунта/организации на GitHub после публикации репозитория.

Содержание

Введение

Wildberries API MCP сервер представляет собой промежуточный сервис, который упрощает взаимодействие с API Wildberries. Он предоставляет унифицированный интерфейс для доступа к данным аналитики, статистике продвижения и другой информации из Wildberries API.

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

Упрощает обращение к различным эндпоинтам API Wildberries
Обрабатывает ошибки и ограничения частоты запросов
Унифицирует формат ответов
Обеспечивает централизованную аутентификацию

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

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

Node.js (версия 14 или выше)
npm или yarn
Docker и Docker Compose (опционально, для контейнеризации)
Токен API Wildberries с соответствующими разрешениями

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

# Клонирование репозитория
git clone https://github.com/yourusername/wb-api-mcp-server.git
cd wb-api-mcp-server

# Установка зависимостей
npm install

# Запуск сервера
npm start

Сервер запустится на порту 3000 по умолчанию. Вы можете указать другой порт, установив переменную окружения PORT:

PORT=8080 npm start

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

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

cp .env.example .env

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

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

npm test    # запускает Jest + Supertest
npm run lint

Оба шага автоматически выполняются в GitHub Actions при каждом push и pull request (см. .github/workflows/ci.yml).

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

# Создание Docker-образа
docker build -t wb-api-mcp-server .

# Запуск Docker-контейнера
docker run -p 3000:3000 -d --name wb-api-mcp wb-api-mcp-server

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

cp .env.example .env
# Запуск сервера с Docker Compose
docker-compose up -d

# Остановка сервера
docker-compose down

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

При каждом push в main GitHub Actions автоматически собирает и публикует образ (см. .github/workflows/docker-publish.yml):

docker pull ghcr.io/ВАШ_ЛОГИН/wb-api-mcp-server:latest
docker run -p 3000:3000 -d --name wb-api-mcp ghcr.io/ВАШ_ЛОГИН/wb-api-mcp-server:latest

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

Вы можете проверить, что сервер работает правильно, отправив запрос к эндпоинту проверки работоспособности:

curl http://localhost:3000/health

Вы должны получить ответ, подобный следующему:

{
  "status": "ok",
  "timestamp": "2023-05-21T12:34:56.789Z"
}

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

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

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

POST /api/adv/fullstats - Статистика рекламных кампаний
GET /api/adv/auto/stat-words - Статистика автоматической кампании по кластерам ключевых фраз
GET /api/adv/stat/words - Статистика кампаний по ключевым фразам
GET /api/adv/stats/keywords - Статистика по ключевым словам для автоматических кампаний
POST /api/adv/stats - Статистика медийных кампаний

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

POST /api/nm-report/detail - Получение статистики карточек товаров за период
POST /api/nm-report/detail/history - Получение статистики карточек товаров по дням
POST /api/nm-report/grouped/history - Получение статистики карточек товаров, сгруппированных по категориям, брендам и тегам

3. Поисковые запросы (Search Queries)

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 - Получение заказов и позиций по поисковым текстам товара

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

POST /api/stocks-report/products/groups - Получение данных по группам товаров для отчета по остаткам
POST /api/stocks-report/products/products - Получение данных по товарам для отчета по остаткам
POST /api/stocks-report/products/sizes - Получение данных по размерам для отчета по остаткам
POST /api/stocks-report/offices - Получение данных по складам для отчета по остаткам

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 - Получение файла отчета

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

POST /api/evirma/import/keywords-report — импорт отчёта «Статистика РК по ключевым фразам» (multipart/form-data, поле file, .xlsx/.xls)
POST /api/evirma/import/daily-zone-stats — импорт отчёта «Статистика РК по дням и зонам показов» (multipart/form-data, поле file, .xlsx/.xls)

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

EVIRMA PRO — платное расширение для Chrome (699₽/мес) с расширенной аналитикой рекламы Wildberries, включая данные официальной подписки WB «Джем». У EVIRMA нет публичного API — данные можно только экспортировать вручную из интерфейса плагина. Этот сервер принимает такую выгрузку и превращает её в структурированный JSON.

Как получить файл

Откройте статистику рекламной кампании по ключевым фразам в EVIRMA PRO.
Экспортируйте таблицу (кнопка экспорта доступна только в PRO-версии).
Загрузите полученный .xlsx-файл в эндпоинт ниже.

Пример запроса

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

Формат ответа

Каждая строка (ключевая фраза/кластер) возвращается со сгруппированными метриками — так же, как они сгруппированы в самой выгрузке EVIRMA:

{
  "error": false,
  "source": "evirma-pro-keywords-report",
  "rowCount": 421,
  "data": [
    {
      "cluster": "5w40",
      "traffic": { "impressions": 250, "clicks": 9, "ctr": 3.6, "spend": 184, "...": "..." },
      "basketsAd": { "baskets": null, "cpl": null, "...": "..." },
      "ordersAd": { "orders": null, "revenue": null, "...": "..." },
      "jemForecast": { "baskets": null, "orders": null, "...": "..." },
      "jemTraffic": { "avgPosition": 98, "visibility": 100, "...": "..." },
      "jemBaskets": { "baskets": null, "...": "..." },
      "jemOrders": { "orders": null, "revenue": null, "...": "..." }
    }
  ]
}

Группы jemForecast, jemTraffic, jemBaskets, jemOrders содержат данные из подписки WB «Джем» (весь трафик, не только рекламный) — они присутствуют в выгрузке, только если у вас подключена подписка «Джем» на Wildberries.

Важно: маппинг колонок (lib/evirmaKeywordsParser.js) привязан к точной структуре конкретного отчёта EVIRMA по состоянию на август 2026. Если разработчик EVIRMA изменит формат экспорта, потребуется обновить COLUMN_MAP в этом файле под новую структуру.

Отчёт «Статистика РК по дням и зонам показов»

POST /api/evirma/import/daily-zone-stats парсит отчёт с разбивкой рекламной статистики по дням и по зонам показа (поиск/каталог). У каждого периода (итог за весь период + по одному на каждый день) есть три группы метрик — ad (реклама), adEfficiency (эффективность рекламы: корзины, заказы, ДРР) и total (весь трафик товара — реклама + органика) — плюс опциональная разбивка zones.search / zones.catalog, если для дня есть данные по этой зоне.

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

{
  "error": false,
  "source": "evirma-pro-daily-zone-stats",
  "rowCount": 27,
  "data": [
    {
      "period": "За период",
      "isSummary": true,
      "date": null,
      "weekday": null,
      "ad": { "impressions": 4578, "cpm": 756, "clicks": 298, "spend": 3460, "...": "..." },
      "adEfficiency": { "baskets": 33, "orders": 7, "revenue": 46403, "drrByRevenue": 7.46, "...": "..." },
      "total": { "views": 26984, "ordersTotal": 43, "revenueTotal": 286865, "...": "..." },
      "zones": {
        "search": { "sharePercent": 97, "ad": { "impressions": 4438, "...": "..." }, "adEfficiency": { "...": "..." } },
        "catalog": { "sharePercent": 3, "ad": { "impressions": 140, "...": "..." }, "adEfficiency": { "...": "..." } }
      }
    },
    {
      "period": "16.08.2026 / вс",
      "isSummary": false,
      "date": "2026-08-16",
      "weekday": "вс",
      "...": "..."
    }
  ]
}

Важно: каталог в zones может быть null — в выгрузке EVIRMA эта строка полностью отсутствует для дней без показов в каталоге (а не просто содержит нули). Маппинг колонок (lib/evirmaDailyStatsParser.js) так же привязан к текущему формату отчёта EVIRMA.

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

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

// Использование fetch
const response = await fetch('http://localhost:3000/api/adv/fullstats', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'api-key': 'ВАШ_ТОКЕН_WILDBERRIES_API'
  },
  body: JSON.stringify([
    {
      "id": 8960367,
      "dates": [
        "2024-04-07",
        "2024-04-06"
      ]
    }
  ])
});

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

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

// Использование axios
const axios = require('axios');

const response = await axios.post('http://localhost:3000/api/nm-report/detail', {
  "brandNames": ["ВашБренд"],
  "objectIDs": [358],
  "tagIDs": [123],
  "nmIDs": [1234567],
  "timezone": "Europe/Moscow",
  "period": {
    "begin": "2024-04-01 00:00:00",
    "end": "2024-04-15 23:59:59"
  },
  "orderBy": {
    "field": "ordersSumRub",
    "mode": "asc"
  },
  "page": 1
}, {
  headers: {
    'api-key': 'ВАШ_ТОКЕН_WILDBERRIES_API'
  }
});

console.log(response.data);

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

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

Сценарий: Вы хотите регулярно отслеживать эффективность ваших рекламных кампаний и анализировать ключевые метрики.