Guía de uso del servidor MCP de Wildberries API

Reemplace TU_LOGIN en las insignias anteriores por el nombre de su cuenta/organización en GitHub después de publicar el repositorio.

Contenido

1. Introducción

2. Instalación y ejecución

3. Herramientas API disponibles

4. Ejemplos de uso

5. Escenarios de uso típicos

6. Obtención del token API

7. Solución de problemas

Introducción

El servidor MCP de Wildberries API es un servicio intermediario que simplifica la interacción con la API de Wildberries. Proporciona una interfaz unificada para acceder a datos de análisis, estadísticas de promoción y otra información de la API de Wildberries.

El servidor MCP realiza las siguientes funciones:

• Simplifica el acceso a los diferentes endpoints de la API de Wildberries

• Gestiona los errores y las limitaciones de frecuencia de las solicitudes

• Unifica el formato de las respuestas

• Proporciona autenticación centralizada

Instalación y ejecución

Requisitos previos necesarios

• Node.js (versión 14 o superior)

• npm o yarn

• Docker y Docker Compose (opcional, para contenerización)

• Token API de Wildberries con los permisos correspondientes

Método 1: Instalación directa mediante Node.js

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

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

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

El servidor se iniciará en el puerto 3000 por defecto. Puede especificar otro puerto configurando la variable de entorno PORT:

PORT=8080 npm start

Variables de entorno

Copie .env.example a .env y edítelo si es necesario:

cp .env.example .env

Pruebas y linter

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

Ambos pasos se ejecutan automáticamente en GitHub Actions en cada push y pull request (ver .github/workflows/ci.yml).

Método 2: Uso de Docker

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

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

Método 3: Uso de Docker Compose

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

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

Método 4: Imagen lista desde GitHub Container Registry

En cada push a main, GitHub Actions compila y publica automáticamente la imagen (ver .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

Verificación de la instalación

Puede comprobar que el servidor funciona correctamente enviando una solicitud al endpoint de verificación de estado:

curl http://localhost:3000/health

Debe obtener una respuesta similar a la siguiente:

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

Herramientas API disponibles

El servidor MCP proporciona los siguientes grupos de endpoints:

1. Estadísticas de promoción (Promotion Statistics)

• POST /api/adv/fullstats - Estadísticas de campañas publicitarias

• GET /api/adv/auto/stat-words - Estadísticas de campañas automáticas por clústeres de frases clave

• GET /api/adv/stat/words - Estadísticas de campañas por frases clave

• GET /api/adv/stats/keywords - Estadísticas por palabras clave para campañas automáticas

• POST /api/adv/stats - Estadísticas de campañas de medios

2. Embudo de ventas (Sales Funnel)

• POST /api/nm-report/detail - Obtención de estadísticas de fichas de productos por período

• POST /api/nm-report/detail/history - Obtención de estadísticas de fichas de productos por días

• POST /api/nm-report/grouped/history - Obtención de estadísticas de fichas de productos agrupadas por categorías, marcas y etiquetas

3. Consultas de búsqueda (Search Queries)

• POST /api/search-report/report - Obtención de datos del informe principal por consultas de búsqueda

• POST /api/search-report/table/groups - Obtención de paginación por grupos para consultas de búsqueda

• POST /api/search-report/table/details - Obtención de paginación por productos dentro de un grupo

• POST /api/search-report/product/search-texts - Obtención de textos de búsqueda por producto

• POST /api/search-report/product/orders - Obtención de pedidos y posiciones por textos de búsqueda de un producto

4. Informe de existencias (Stocks Report)

• POST /api/stocks-report/products/groups - Obtención de datos por grupos de productos para el informe de existencias

• POST /api/stocks-report/products/products - Obtención de datos por productos para el informe de existencias

• POST /api/stocks-report/products/sizes - Obtención de datos por tallas para el informe de existencias

• POST /api/stocks-report/offices - Obtención de datos por almacenes para el informe de existencias

5. Informes CSV del vendedor (Seller Analytics CSV)

• POST /api/nm-report/downloads - Creación de un informe CSV

• GET /api/nm-report/downloads - Obtención de la lista de informes

• POST /api/nm-report/downloads/retry - Regeneración de un informe

• GET /api/nm-report/downloads/file/:downloadId - Obtención del archivo del informe

6. Importación de datos de EVIRMA PRO

• POST /api/evirma/import/keywords-report — importación del informe «Estadísticas de campañas publicitarias por frases clave» (multipart/form-data, campo file, .xlsx/.xls)

• POST /api/evirma/import/daily-zone-stats — importación del informe «Estadísticas de campañas publicitarias por días y zonas de visualización» (multipart/form-data, campo file, .xlsx/.xls)

Importación de informes de EVIRMA PRO

EVIRMA PRO — extensión de pago para Chrome (699₽/mes) con análisis ampliado de la publicidad de Wildberries, incluidos los datos de la suscripción oficial de WB «Dzhem». EVIRMA no tiene API pública: los datos solo se pueden exportar manualmente desde la interfaz del plugin. Este servidor acepta dicha exportación y la convierte en JSON estructurado.

Cómo obtener el archivo

1. Abra las estadísticas de la campaña publicitaria por frases clave en EVIRMA PRO.

2. Exporte la tabla (el botón de exportación solo está disponible en la versión PRO).

3. Cargue el archivo .xlsx obtenido en el endpoint siguiente.

Ejemplo de solicitud

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

Formato de respuesta

Cada fila (frase clave/clúster) se devuelve con métricas agrupadas, tal como están agrupadas en la propia exportación de 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, "...": "..." }
    }
  ]
}

Los grupos jemForecast, jemTraffic, jemBaskets, jemOrders contienen datos de la suscripción WB «Dzhem» (todo el tráfico, no solo el publicitario): están presentes en la exportación solo si tiene conectada la suscripción «Dzhem» en Wildberries.

Importante: el mapeo de columnas (lib/evirmaKeywordsParser.js) está vinculado a la estructura exacta del informe concreto de EVIRMA a fecha de agosto de 2026. Si el desarrollador de EVIRMA cambia el formato de exportación, será necesario actualizar COLUMN_MAP en ese archivo para adaptarlo a la nueva estructura.

Informe «Estadísticas de campañas publicitarias por días y zonas de visualización»

POST /api/evirma/import/daily-zone-stats analiza el informe con el desglose de las estadísticas publicitarias por días y por zonas de visualización (búsqueda/catálogo). Cada período (total de todo el período + uno por cada día) tiene tres grupos de métricas: ad (publicidad), adEfficiency (eficacia de la publicidad: cestas, pedidos, DRR) y total (todo el tráfico del producto: publicidad + orgánico), más un desglose opcional zones.search / zones.catalog, si hay datos para esa zona en ese día.

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": "вс",
      "...": "..."
    }
  ]
}

Importante: catalog en zones puede ser null: en la exportación de EVIRMA esa fila está completamente ausente para los días sin impresiones en el catálogo (no es que contenga ceros). El mapeo de columnas (lib/evirmaDailyStatsParser.js) también está vinculado al formato actual del informe de EVIRMA.

Ejemplos de uso

Obtención de estadísticas de campañas publicitarias

// Использование 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);

Obtención de estadísticas de fichas de productos

// Использование 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);

Escenarios de uso típicos

1. Monitorización de la eficacia de las campañas publicitarias

Escenario: Desea realizar un seguimiento periódico de la eficacia de sus campañas publicitarias y analizar las métricas clave.

Solución con MCP:

1. Configure una tarea diaria que solicite las estadísticas de todas las campañas activas.

2. Guarde los datos obtenidos en una base de datos para su análisis histórico.

3. Cree un panel que muestre las métricas clave (CTR, conversiones, costes).

Ejemplo de código:

// Получение статистики кампаний
const campaigns = [123456, 789012]; // ID ваших кампаний
const dates = [getDateString(new Date())]; // Сегодняшняя дата

// Формирование запроса
const requestData = campaigns.map(id => ({
  id: id,
  dates: dates
}));

// Отправка запроса к MCP серверу
const campaignStats = await fetchFromMcp('/api/adv/fullstats', 'POST', requestData);

// Сохранение данных и генерация отчета
saveToDatabaseAndGenerateReport(campaignStats);

2. Análisis del embudo de ventas de los productos

Escenario: Desea analizar cómo interactúan los usuarios con sus productos, desde la visualización de la ficha hasta la compra.

Solución con MCP:

1. Solicite estadísticas detalladas de los productos para el período seleccionado.

2. Analice las conversiones en cada etapa (visualización → adición al carrito → pedido → compra).

3. Identifique los productos con bajas conversiones para optimizarlos.

Ejemplo de código:

// Получение статистики воронки продаж
const response = await fetchFromMcp('/api/nm-report/detail', 'POST', {
  "nmIDs": [/* ваши номенклатуры */],
  "timezone": "Europe/Moscow",
  "period": {
    "begin": "2024-04-01 00:00:00",
    "end": "2024-04-30 23:59:59"
  },
  "page": 1
});

// Анализ конверсий
const products = response.data.cards;
const lowConversionProducts = products.filter(product => {
  const stats = product.statistics.selectedPeriod;
  return stats.conversions.addToCartPercent < 5 || 
         stats.conversions.cartToOrderPercent < 20 ||
         stats.conversions.buyoutsPercent < 80;
});

// Генерация отчета по проблемным товарам
generateLowConversionReport(lowConversionProducts);

3. Optimización de la visibilidad en la búsqueda

Escenario: Desea mejorar la visibilidad de sus productos en la búsqueda de Wildberries.

Solución con MCP:

1. Solicite informes de consultas de búsqueda para sus productos.

2. Analice en qué consultas sus productos tienen buenas posiciones y en cuáles malas.

3. Optimice las fichas de los productos para mejorar las posiciones.

Ejemplo de código:

// Получение отчета по поисковым запросам
const searchReport = await fetchFromMcp('/api/search-report/report', 'POST', {
  "currentPeriod": {
    "start": "2024-04-01",
    "end": "2024-04-30"
  },
  "positionCluster": "all",
  "orderBy": {
    "field": "avgPosition",
    "mode": "desc"
  },
  "limit": 100,
  "offset": 0
});

// Получение поисковых текстов для конкретного товара
const searchTexts = await fetchFromMcp('/api/search-report/product/search-texts', 'POST', {
  "currentPeriod": {
    "start": "2024-04-01",
    "end": "2024-04-30"
  },
  "nmIds": [1234567],
  "topOrderBy": "openCard",
  "limit": 20
});

// Анализ результатов и формирование рекомендаций
analyzeSearchPositionsAndGenerateRecommendations(searchTexts);

4. Gestión de existencias basada en análisis

Escenario: Desea optimizar el nivel de existencias de los productos en los almacenes basándose en los datos de ventas.

Solución con MCP:

1. Solicite periódicamente informes de existencias y ventas.

2. Calcule el nivel óptimo de existencias basándose en la velocidad de ventas.

3. Identifique los productos con existencias excesivas o insuficientes.

Ejemplo de código:

// Получение отчета по остаткам
const stocksReport = await fetchFromMcp('/api/stocks-report/products/products', 'POST', {
  "nmIDs": [/* ваши номенклатуры */],
  "currentPeriod": {
    "start": "2024-04-01",
    "end": "2024-04-30"
  },
  "stockType": "",
  "skipDeletedNm": true,
  "orderBy": {
    "field": "avgOrders",
    "mode": "desc"
  },
  "offset": 0
});

// Анализ скорости продаж и остатков
const stockOptimizationReport = stocksReport.data.items.map(item => {
  const dailySales = item.metrics.avgOrders;
  const currentStock = item.metrics.stockCount;
  const daysOfSupply = currentStock / dailySales;
  
  return {
    nmId: item.nmID,
    name: item.name,
    dailySales,
    currentStock,
    daysOfSupply,
    stockStatus: daysOfSupply < 7 ? 'LOW' : daysOfSupply > 30 ? 'HIGH' : 'OPTIMAL'
  };
});

// Генерация рекомендаций по управлению запасами
generateStockManagementRecommendations(stockOptimizationReport);

5. Generación y análisis de informes CSV ampliados

Escenario: Desea obtener datos detallados para un análisis profundo en Excel u otra herramienta.

Solución con MCP:

1. Cree una tarea de generación de informe CSV a través de MCP.

2. Espere a que finalice la generación y descargue el informe.

3. Importe los datos en herramientas de análisis para su estudio.

Ejemplo de código:

// Создание задачи на генерацию отчета
const reportId = generateUUID();
const createReportResponse = await fetchFromMcp('/api/nm-report/downloads', 'POST', {
  "id": reportId,
  "reportType": "DETAIL_HISTORY_REPORT",
  "userReportName": "Аналитика по товарам за апрель",
  "params": {
    "nmIDs": [/* ваши номенклатуры */],
    "startDate": "2024-04-01",
    "endDate": "2024-04-30",
    "timezone": "Europe/Moscow",
    "aggregationLevel": "day",
    "skipDeletedNm": false
  }
});

// Проверка статуса генерации (через некоторое время)
setTimeout(async () => {
  const reportStatusResponse = await fetchFromMcp('/api/nm-report/downloads', 'GET', {
    'filter[downloadIds]': [reportId]
  });
  
  const reportStatus = reportStatusResponse.data[0].status;
  
  if (reportStatus === 'SUCCESS') {
    // Загрузка отчета
    downloadReport(reportId);
  } else if (reportStatus === 'FAILED') {
    // Повторная попытка генерации
    retryReport(reportId);
  }
}, 60000); // Проверка через 1 минуту

Obtención del token API

Para trabajar con la API de Wildberries a través del servidor MCP necesitará un token API. Así puede obtenerlo:

1. Acceda a su cuenta personal de vendedor de Wildberries

   Vaya a seller.wildberries.ru e inicie sesión.

2. Vaya a la sección de configuración de API

   Tras iniciar sesión, vaya a la sección «Configuración» (normalmente disponible desde el menú o el perfil).

3. Vaya a la sección de gestión de API

   Busque la sección «API» o «Acceso a API» o «Integración».

4. Cree un nuevo token API

   • Haga clic en «Crear nuevo token» o en un botón similar

   • Seleccione los permisos de acceso necesarios para el token:

     • Para el servidor MCP de WB API necesitará:

       • Permiso de la categoría Analítica para el embudo de ventas y las consultas de búsqueda

       • Permiso de la categoría Promoción para las estadísticas de publicidad

   • Indique un nombre para el token (para su comodidad)

   • Si es necesario, establezca un período de validez (o déjelo permanente)

5. Genere y guarde el token

   Tras rellenar la información necesaria, haga clic en «Generar» o «Crear» para generar el token API.

   IMPORTANTE: Asegúrese de copiar y guardar su token de forma segura. El token completo solo se mostrará una vez por motivos de seguridad.

Solución de problemas

Problemas frecuentes

1. Fallo de conexión: Asegúrese de que el servidor está en ejecución y de que el puerto es accesible.

2. Errores de autenticación: Compruebe que su token API de Wildberries es válido y tiene los permisos necesarios.

3. Límite de frecuencia de solicitudes: El servidor gestiona las limitaciones de frecuencia de la API de Wildberries, pero es posible que deba esperar si ha superado el número permitido de solicitudes.

Visualización de registros

Al ejecutarse con Docker o Docker Compose, los registros se almacenan en el directorio logs, que está montado como volumen.

Para ver los registros en un contenedor Docker en ejecución:

docker logs wb-api-mcp

Códigos de error

• 401 - Error de autenticación (compruebe su token API)

• 429 - Límite de solicitudes superado (espere un tiempo)

• 400 - Solicitud incorrecta (compruebe los parámetros de la solicitud)

• 403 - Acceso denegado (compruebe los permisos de su token)

Despliegue en Cloudflare Workers

El servidor también se puede desplegar como Cloudflare Worker (mediante wrangler deploy o autodespliegue desde GitHub en Cloudflare Dashboard) — Cloudflare desde 2026 soporta oficialmente la ejecución de aplicaciones Express en Workers a través del adaptador cloudflare:node. De esto se encargan dos archivos: wrangler.jsonc (configuración) y worker-entry.mjs (punto de entrada-envoltorio). El arranque normal mediante npm start/Docker no los utiliza ni los requiere.

npm run deploy:cloudflare
# или напрямую:
npx wrangler deploy

Requisitos: Node.js ≥20 en el entorno de compilación (en Cloudflare Dashboard se establece automáticamente mediante .nvmrc, o con la variable NODE_VERSION en Settings → Build).

Limitaciones importantes en comparación con Docker/alojamiento Node normal:

• Rate limiting (express-rate-limit) almacena los contadores en la memoria del proceso. En Workers los aislamientos se recrean periódicamente, por lo que el límite de solicitudes puede reiniciarse con más frecuencia que en un servidor en funcionamiento continuo — para un limitado estricto en producción se recomiendan Cloudflare Rate Limiting Rules a nivel de plataforma en lugar de (o junto con) express-rate-limit.

• El tiempo de CPU por solicitud está limitado por la tarifa de Cloudflare (especialmente en el plan gratuito) — el análisis de archivos .xlsx grandes mediante /api/evirma/import/* puede chocar con el límite en cargas realmente grandes.

• Los archivos subidos (multer) se procesan solo en la memoria de la solicitud — esto ya era así en Docker, aquí no cambia nada.

Si se necesita un runtime Node completamente predecible sin estas salvedades — use el despliegue Docker normal (ver arriba), para el cual el servidor fue escrito originalmente.

Seguridad y operación en producción

• HTTPS es obligatorio en producción. El servidor por sí mismo no termina TLS — despliéguelo detrás de un reverse-proxy (nginx, Caddy, Cloudflare Tunnel, etc.), de lo contrario el token api-key se transmitirá en texto plano.

• El token no se almacena en ningún lugar del servidor — el cliente lo envía en el encabezado api-key en cada solicitud y se usa únicamente para el proxy hacia la API de Wildberries.

• /health no requiere autorización — está diseñado para monitoreo y healthchecks de Docker/Kubernetes y no devuelve datos sensibles.

• Rate limiting — el límite integrado RATE_LIMIT_MAX de solicitudes por minuto desde una misma IP protege contra ráfagas accidentales de solicitudes a la API de Wildberries.

• Escaneo automático de dependencias y código — Dependabot (npm/Docker/Actions) y CodeQL se ejecutan semanalmente y en cada PR (ver .github/).

• El contenedor se ejecuta con un usuario sin privilegios (appuser), no como root.

• Carga de archivos (/api/evirma/import/keywords-report) está limitada a 15 MB y a las extensiones .xlsx/.xls; el archivo se procesa solo en memoria (no se guarda en disco).