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

Leitfaden zur Verwendung des Wildberries API MCP-Servers

Docker publish

Ersetzen Sie ВАШ_ЛОГИН in den obigen Badges durch den Namen Ihres GitHub-Kontos/Ihrer Organisation, nachdem Sie das Repository veröffentlicht haben.

Inhaltsverzeichnis

Einführung

Der Wildberries API MCP-Server ist ein Zwischendienst, der die Interaktion mit der Wildberries-API vereinfacht. Er bietet eine einheitliche Schnittstelle für den Zugriff auf Analysedaten, Werbestatistiken und andere Informationen aus der Wildberries-API.

Der MCP-Server übernimmt folgende Funktionen:

Vereinfacht den Zugriff auf verschiedene Endpunkte der Wildberries-API
Behandelt Fehler und Ratenbegrenzungen (Rate Limits)
Vereinheitlicht das Antwortformat
Bietet zentrale Authentifizierung

Installation und Start

Voraussetzungen

Node.js (Version 14 oder höher)
npm oder yarn
Docker und Docker Compose (optional, für Containerisierung)
Wildberries-API-Token mit entsprechenden Berechtigungen

Methode 1: Direkte Installation über Node.js

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

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

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

Der Server startet standardmäßig auf Port 3000. Sie können einen anderen Port angeben, indem Sie die Umgebungsvariable PORT setzen:

PORT=8080 npm start

Umgebungsvariablen

Kopieren Sie .env.example in .env und bearbeiten Sie es bei Bedarf:

cp .env.example .env

Variable	Standard	Beschreibung
`PORT`	`3000`	Port, auf dem der Server lauscht
`NODE_ENV`	`production`	`production` / `development` / `test`
`RATE_LIMIT_MAX`	`100`	Maximale Anzahl von Anfragen von einer IP pro Minute

Tests und Linter

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

Beide Schritte werden in GitHub Actions bei jedem Push und Pull Request automatisch ausgeführt (siehe .github/workflows/ci.yml).

Methode 2: Verwendung von Docker

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

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

Methode 3: Verwendung von Docker Compose

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

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

Methode 4: Fertiges Image aus der GitHub Container Registry

Bei jedem Push in main erstellt und veröffentlicht GitHub Actions automatisch ein Image (siehe .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

Installation überprüfen

Sie können überprüfen, ob der Server ordnungsgemäß funktioniert, indem Sie eine Anfrage an den Health-Check-Endpunkt senden:

curl http://localhost:3000/health

Sie sollten eine Antwort wie die folgende erhalten:

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

Verfügbare API-Tools

Der MCP-Server stellt die folgenden Endpunktgruppen bereit:

1. Werbestatistik (Promotion Statistics)

POST /api/adv/fullstats – Statistik der Werbekampagnen
GET /api/adv/auto/stat-words – Statistik der automatischen Kampagne nach Schlüsselphrasen-Clustern
GET /api/adv/stat/words – Statistik der Kampagnen nach Schlüsselphrasen
GET /api/adv/stats/keywords – Statistik zu Schlüsselwörtern für automatische Kampagnen
POST /api/adv/stats – Statistik der Medienkampagnen

2. Verkaufstrichter (Sales Funnel)

POST /api/nm-report/detail – Abruf der Statistik der Produktkarten für einen Zeitraum
POST /api/nm-report/detail/history – Abruf der Statistik der Produktkarten nach Tagen
POST /api/nm-report/grouped/history – Abruf der Statistik der Produktkarten, gruppiert nach Kategorien, Marken und Tags

3. Suchanfragen (Search Queries)

POST /api/search-report/report – Abruf der Daten des Hauptberichts zu Suchanfragen
POST /api/search-report/table/groups – Abruf der Paginierung nach Gruppen für Suchanfragen
POST /api/search-report/table/details – Abruf der Paginierung nach Produkten innerhalb einer Gruppe
POST /api/search-report/product/search-texts – Abruf der Suchtexte zu einem Produkt
POST /api/search-report/product/orders – Abruf von Bestellungen und Positionen zu den Suchtexten eines Produkts

4. Bestandsbericht (Stocks Report)

POST /api/stocks-report/products/groups – Abruf der Daten zu Produktgruppen für den Bestandsbericht
POST /api/stocks-report/products/products – Abruf der Daten zu Produkten für den Bestandsbericht
POST /api/stocks-report/products/sizes – Abruf der Daten zu Größen für den Bestandsbericht
POST /api/stocks-report/offices – Abruf der Daten zu Lagern für den Bestandsbericht

5. CSV-Berichte des Verkäufers (Seller Analytics CSV)

POST /api/nm-report/downloads – Erstellung eines CSV-Berichts
GET /api/nm-report/downloads – Abruf der Liste der Berichte
POST /api/nm-report/downloads/retry – Erneute Generierung des Berichts
GET /api/nm-report/downloads/file/:downloadId – Abruf der Berichtsdatei

6. Import von EVIRMA PRO-Daten

POST /api/evirma/import/keywords-report – Import des Berichts „Statistik der Werbekampagnen nach Schlüsselphrasen“ (multipart/form-data, Feld file, .xlsx/.xls)
POST /api/evirma/import/daily-zone-stats – Import des Berichts „Statistik der Werbekampagnen nach Tagen und Anzeigezonen“ (multipart/form-data, Feld file, .xlsx/.xls)

Import von EVIRMA PRO-Berichten

EVIRMA PRO ist eine kostenpflichtige Chrome-Erweiterung (699 ₽/Monat) mit erweiterter Wildberries-Werbeanalyse, einschließlich Daten des offiziellen WB-Abonnements „Джем“. EVIRMA hat keine öffentliche API – Daten können nur manuell über die Plugin-Oberfläche exportiert werden. Dieser Server nimmt einen solchen Export entgegen und wandelt ihn in strukturiertes JSON um.

So erhalten Sie die Datei

Öffnen Sie die Statistik der Werbekampagne nach Schlüsselphrasen in EVIRMA PRO.
Exportieren Sie die Tabelle (die Export-Schaltfläche ist nur in der PRO-Version verfügbar).
Laden Sie die erhaltene .xlsx-Datei in den untenstehenden Endpunkt hoch.

Beispielanfrage

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

Antwortformat

Jede Zeile (Schlüsselphrase/Cluster) wird mit gruppierten Metriken zurückgegeben – genau so, wie sie im EVIRMA-Export selbst gruppiert sind:

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

Die Gruppen jemForecast, jemTraffic, jemBaskets, jemOrders enthalten Daten aus dem WB-Abonnement „Джем“ (gesamter Traffic, nicht nur Werbung) – sie sind im Export nur vorhanden, wenn bei Ihnen das Abonnement „Джем“ auf Wildberries aktiviert ist.

Wichtig: Das Spalten-Mapping (lib/evirmaKeywordsParser.js) ist an die genaue Struktur des jeweiligen EVIRMA-Berichts mit Stand August 2026 gebunden. Wenn der Entwickler von EVIRMA das Exportformat ändert, muss COLUMN_MAP in dieser Datei an die neue Struktur angepasst werden.

Bericht „Statistik der Werbekampagnen nach Tagen und Anzeigezonen“

POST /api/evirma/import/daily-zone-stats parst den Bericht mit der Aufschlüsselung der Werbestatistik nach Tagen und Anzeigezonen (Suche/Katalog). Jeder Zeitraum (Gesamtsumme für den gesamten Zeitraum + einer pro Tag) hat drei Metrikgruppen – ad (Werbung), adEfficiency (Werbeeffizienz: Warenkörbe, Bestellungen, Werbeausgabenanteil) und total (gesamter Produkttraffic – Werbung + organisch) – plus eine optionale Aufschlüsselung zones.search / zones.catalog, falls für den Tag Daten zu dieser Zone vorliegen.

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

Wichtig: каталог in zones kann null sein – im EVIRMA-Export fehlt diese Zeile für Tage ohne Katalog-Impressions vollständig (und enthält nicht einfach Nullen). Das Spalten-Mapping (lib/evirmaDailyStatsParser.js) ist ebenfalls an das aktuelle Format des EVIRMA-Berichts gebunden.

Anwendungsbeispiele

Abruf der Statistik von Werbekampagnen

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

Abruf der Statistik von Produktkarten

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

Typische Anwendungsszenarien

1. Überwachung der Effektivität von Werbekampagnen

Szenario: Sie möchten regelmäßig die Effektivität Ihrer Werbekampagnen verfolgen und wichtige Kennzahlen analysieren.