Guide to using the Wildberries API MCP server

Replace ВАШ_ЛОГИН in the badges above with the name of your GitHub account/organization after publishing the repository.

Table of Contents

1. Introduction

2. Installation and Launch

3. Available API Tools

4. Usage Examples

5. Typical Use Cases

6. Obtaining an API Token

7. Troubleshooting

Introduction

The Wildberries API MCP server is an intermediary service that simplifies interaction with the Wildberries API. It provides a unified interface for accessing analytics data, promotion statistics, and other information from the Wildberries API.

The MCP server performs the following functions:

• Simplifies access to various Wildberries API endpoints

• Handles errors and rate limits

• Unifies the response format

• Provides centralized authentication

Installation and Launch

Prerequisites

• Node.js (version 14 or higher)

• npm or yarn

• Docker and Docker Compose (optional, for containerization)

• Wildberries API token with the appropriate permissions

Method 1: Direct installation via Node.js

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

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

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

The server will start on port 3000 by default. You can specify a different port by setting the PORT environment variable:

PORT=8080 npm start

Environment Variables

Copy .env.example to .env and edit if necessary:

cp .env.example .env

Tests and Linter

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

Both steps are automatically executed in GitHub Actions on every push and pull request (see .github/workflows/ci.yml).

Method 2: Using Docker

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

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

Method 3: Using Docker Compose

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

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

Method 4: Ready-made image from GitHub Container Registry

On every push to main, GitHub Actions automatically builds and publishes the image (see .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

Verifying the Installation

You can verify that the server is working correctly by sending a request to the health check endpoint:

curl http://localhost:3000/health

You should receive a response similar to the following:

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

Available API Tools

The MCP server provides the following groups of endpoints:

1. Promotion Statistics

• POST /api/adv/fullstats - Advertising campaign statistics

• GET /api/adv/auto/stat-words - Automatic campaign statistics by key phrase clusters

• GET /api/adv/stat/words - Campaign statistics by key phrases

• GET /api/adv/stats/keywords - Statistics by keywords for automatic campaigns

• POST /api/adv/stats - Media campaign statistics

2. Sales Funnel

• POST /api/nm-report/detail - Getting product card statistics for a period

• POST /api/nm-report/detail/history - Getting product card statistics by day

• POST /api/nm-report/grouped/history - Getting product card statistics grouped by categories, brands, and tags

3. Search Queries

• POST /api/search-report/report - Getting data from the main search query report

• POST /api/search-report/table/groups - Getting pagination by groups for search queries

• POST /api/search-report/table/details - Getting pagination by products within a group

• POST /api/search-report/product/search-texts - Getting search texts for a product

• POST /api/search-report/product/orders - Getting orders and positions by product search texts

4. Stocks Report

• POST /api/stocks-report/products/groups - Getting data on product groups for the stocks report

• POST /api/stocks-report/products/products - Getting data on products for the stocks report

• POST /api/stocks-report/products/sizes - Getting data on sizes for the stocks report

• POST /api/stocks-report/offices - Getting data on warehouses for the stocks report

5. Seller Analytics CSV

• POST /api/nm-report/downloads - Creating a CSV report

• GET /api/nm-report/downloads - Getting a list of reports

• POST /api/nm-report/downloads/retry - Regenerating a report

• GET /api/nm-report/downloads/file/:downloadId - Getting the report file

6. EVIRMA PRO Data Import

• POST /api/evirma/import/keywords-report — import of the "Campaign statistics by key phrases" report (multipart/form-data, field file, .xlsx/.xls)

• POST /api/evirma/import/daily-zone-stats — import of the "Campaign statistics by days and display zones" report (multipart/form-data, field file, .xlsx/.xls)

Importing EVIRMA PRO Reports

EVIRMA PRO is a paid Chrome extension (699₽/month) with advanced Wildberries advertising analytics, including data from the official WB "Jem" subscription. EVIRMA has no public API — data can only be exported manually from the plugin interface. This server accepts such an export and turns it into structured JSON.

How to get the file

1. Open the advertising campaign statistics by key phrases in EVIRMA PRO.

2. Export the table (the export button is available only in the PRO version).

3. Upload the resulting .xlsx file to the endpoint below.

Example request

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

Response format

Each row (key phrase/cluster) is returned with grouped metrics — just as they are grouped in the EVIRMA export itself:

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

The jemForecast, jemTraffic, jemBaskets, jemOrders groups contain data from the WB "Jem" subscription (all traffic, not just advertising) — they are present in the export only if you have the "Jem" subscription enabled on Wildberries.

Important: the column mapping (lib/evirmaKeywordsParser.js) is tied to the exact structure of the specific EVIRMA report as of August 2026. If the EVIRMA developer changes the export format, you will need to update COLUMN_MAP in this file to match the new structure.

Report "Campaign statistics by days and display zones"

POST /api/evirma/import/daily-zone-stats parses the report with advertising statistics broken down by days and display zones (search/catalog). Each period (total for the entire period + one for each day) has three metric groups — ad (advertising), adEfficiency (advertising efficiency: baskets, orders, DRR) and total (all product traffic — advertising + organic) — plus an optional breakdown zones.search / zones.catalog, if there is data for that zone for the day.

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

Important: catalog in zones can be null — in the EVIRMA export this row is completely absent for days without catalog impressions (rather than simply containing zeros). The column mapping (lib/evirmaDailyStatsParser.js) is also tied to the current EVIRMA report format.

Usage Examples

Getting advertising campaign statistics

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

Getting product card statistics

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

Typical Use Cases

1. Monitoring advertising campaign effectiveness

Scenario: You want to regularly track the effectiveness of your advertising campaigns and analyze key metrics.

Solution using MCP:

1. Set up a daily task that requests statistics for all active campaigns.

2. Save the received data to a database for historical analysis.

3. Create a dashboard displaying key metrics (CTR, conversions, costs).

Code example:

// Получение статистики кампаний
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. Analyzing the product sales funnel

Scenario: You want to analyze how users interact with your products from viewing the card to purchase.

Solution using MCP:

1. Request detailed product statistics for the selected period.

2. Analyze conversions at each stage (view → add to cart → order → purchase).

3. Identify products with low conversions for optimization.

Code example:

// Получение статистики воронки продаж
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. Optimizing search visibility

Scenario: You want to improve the visibility of your products in Wildberries search.

Solution using MCP:

1. Request search query reports for your products.

2. Analyze which queries your products rank well for and which they rank poorly for.

3. Optimize product cards to improve rankings.

Code example:

// Получение отчета по поисковым запросам
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. Inventory management based on analytics

Scenario: You want to optimize the level of product inventory in warehouses based on sales data.

Solution using MCP:

1. Regularly request stock and sales reports.

2. Calculate the optimal inventory level based on sales velocity.

3. Identify products with excess or insufficient inventory.

Code example:

// Получение отчета по остаткам
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. Generating and analyzing advanced CSV reports

Scenario: You want to obtain detailed data for in-depth analysis in Excel or another tool.

Solution using MCP:

1. Create a task to generate a CSV report via MCP.

2. Wait for the generation to complete and download the report.

3. Import the data into analytical tools for analysis.

Code example:

// Создание задачи на генерацию отчета
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 минуту

Obtaining an API Token

To work with the Wildberries API through the MCP server, you will need an API token. Here is how to get it:

1. Log in to your Wildberries seller account

   Go to seller.wildberries.ru and sign in.

2. Go to the API settings section

   After logging in, go to the "Settings" section (usually available from the menu or profile).

3. Go to the API management section

   Find the "API" or "API Access" or "Integration" section.

4. Create a new API token

   • Click "Create new token" or a similar button

   • Select the required access permissions for the token:

     • For the WB API MCP server you will need:

       • Permission of the Analytics category for the sales funnel and search queries

       • Permission of the Promotion category for advertising statistics

   • Specify a name for the token (for your convenience)

   • If necessary, set an expiration date (or leave it permanent)

5. Generate and save the token

   After filling in the required information, click "Generate" or "Create" to generate the API token.

   IMPORTANT: Be sure to copy and securely store your token! The full token will be shown only once for security purposes.

Troubleshooting

Common issues

1. Connection refused: Make sure the server is running and the port is available.

2. Authentication errors: Check that your Wildberries API token is valid and has the necessary permissions.

3. Rate limiting: The server handles Wildberries API rate limits, but you may need to wait if you have exceeded the allowed number of requests.

Viewing logs

When running with Docker or Docker Compose, logs are stored in the logs directory, which is mounted as a volume.

To view logs in a running Docker container:

docker logs wb-api-mcp

Error codes

• 401 - Authentication error (check your API token)

• 429 - Rate limit exceeded (wait for a while)

• 400 - Bad request (check the request parameters)

• 403 - Access denied (check your token permissions)

Deploying to Cloudflare Workers

The server can also be deployed as a Cloudflare Worker (via wrangler deploy or auto-deploy from GitHub to Cloudflare Dashboard) — as of 2026, Cloudflare officially supports running Express applications on Workers through the cloudflare:node adapter. Two files are responsible for this: wrangler.jsonc (configuration) and worker-entry.mjs (entry-point wrapper). Normal startup via npm start/Docker does not use or require them.

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

Requirements: Node.js ≥20 in the build environment (set automatically in Cloudflare Dashboard via .nvmrc, or via the NODE_VERSION variable in Settings → Build).

Important limitations compared to Docker/regular Node hosting:

• Rate limiting (express-rate-limit) stores counters in the process memory. On Workers, isolates are periodically recreated, so the request limit may reset more often than on an always-running server — for strict rate limiting in production, Cloudflare Rate Limiting Rules at the platform level are recommended instead of (or alongside) express-rate-limit.

• CPU time per request is limited by the Cloudflare plan (especially on the free plan) — parsing large .xlsx files via /api/evirma/import/* may hit the limit on truly large exports.

• Uploaded files (multer) are processed only in the request memory — this was already the case on Docker, and nothing changes here.

If you need a fully predictable Node.js runtime without these caveats, use the regular Docker deployment (see above), for which the server was originally written.

Security and production operation

• HTTPS is mandatory in production. The server itself does not terminate TLS — deploy it behind a reverse proxy (nginx, Caddy, Cloudflare Tunnel, etc.), otherwise the api-key token will be transmitted in plain text.

• The token is not stored anywhere on the server — it is sent by the client in the api-key header with every request and is used only for proxying to the Wildberries API.

• /health does not require authorization — it is intended for monitoring and Docker/Kubernetes healthchecks and does not expose sensitive data.

• Rate limiting — the built-in RATE_LIMIT_MAX limit of requests per minute from a single IP protects against accidental burst requests to the Wildberries API.

• Automated dependency and code scanning — Dependabot (npm/Docker/Actions) and CodeQL run weekly and on every PR (see .github/).

• The container runs as an unprivileged user (appuser), not as root.

• File upload (/api/evirma/import/keywords-report) is limited to 15 MB and .xlsx/.xls extensions; the file is processed only in memory (not saved to disk).