wildberries-api-mcp-server by dmitriipolushin - MCP Server

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

Содержание

Введение
Установка и запуск
Доступные инструменты API
Примеры использования
Типичные сценарии использования
Получение токена API
Устранение неполадок

Введение

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

Способ 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

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

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

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

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

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

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

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

// Использование 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. Мониторинг эффективности рекламных кампаний

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