Skip to main content
Glama
antondrpq

Wildberries API MCP Server

by antondrpq

Wildberries API MCPサーバー利用ガイド

CI Docker publish

上記のバッジのВАШ_ЛОГИНは、リポジトリ公開後にGitHubのアカウント名/組織名に置き換えてください。

目次

  1. はじめに

  2. インストールと起動

  3. 利用可能なAPIツール

  4. 使用例

  5. 典型的な利用シナリオ

  6. APIトークンの取得

  7. トラブルシューティング

Related MCP server: Wildberries MCP Server

はじめに

Wildberries API MCPサーバーは、Wildberries APIとの連携を簡素化する中間サービスです。分析データ、プロモーション統計、その他のWildberries API情報へのアクセスに統一されたインターフェースを提供します。

MCPサーバーは以下の機能を実行します:

  • Wildberries APIの様々なエンドポイントへのアクセスを簡素化

  • エラーとリクエスト頻度制限の処理

  • レスポンス形式の統一

  • 集中認証の提供

インストールと起動

必要な前提条件

  • Node.js(バージョン14以上)

  • npmまたはyarn

  • DockerおよびDocker Compose(オプション、コンテナ化用)

  • 適切な権限を持つWildberries APIトークン

方法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

1分間に1つのIPから受け付ける最大リクエスト数

テストとリンター

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

両方のステップは、GitHub Actionsでプッシュおよびプルリクエストのたびに自動的に実行されます(.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からの既製イメージ

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 — Wildberries広告の高度な分析を提供するChrome用有料拡張機能(699₽/月)で、WB公式サブスクリプション「Джем」のデータも含まれます。EVIRMAには公開APIがなく、データはプラグインのインターフェースから手動でエクスポートするしかありません。このサーバーはそのようなエクスポートデータを受け取り、構造化されたJSONに変換します。

ファイルの取得方法

  1. EVIRMA PROでキーフレーズ別の広告キャンペーン統計を開きます。

  2. テーブルをエクスポートします(エクスポートボタンはPRO版でのみ利用可能です)。

  3. 取得した.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)は、2026年8月時点の特定のEVIRMAレポートの正確な構造に依存しています。EVIRMAの開発者がエクスポート形式を変更した場合は、このファイルのCOLUMN_MAPを新しい構造に合わせて更新する必要があります。

「日別・表示ゾーン別キャンペーン統計」レポート

POST /api/evirma/import/daily-zone-statsは、広告統計を日別および表示ゾーン別(検索/カタログ)に分類したレポートを解析します。各期間(全期間の合計+日ごとに1つ)には、ad(広告)、adEfficiency(広告効率:カート、注文、DRR)、total(商品の全トラフィック — 広告+オーガニック)の3つのメトリクスグループがあり、さらにその日にそのゾーンのデータがある場合はオプションの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. 広告キャンペーンの効果モニタリング

シナリオ: 広告キャンペーンの効果を定期的に追跡し、主要なメトリクスを分析したい場合。

MCPを使用した解決策:

  1. すべてのアクティブなキャンペーンの統計をリクエストする毎日のタスクを設定します。

  2. 取得したデータを履歴分析用にデータベースに保存します。

  3. 主要なメトリクス(CTR、コンバージョン、コスト)を表示するダッシュボードを作成します。

コード例:

// Получение статистики кампаний
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. 商品の販売ファネル分析

シナリオ: ユーザーがカードの閲覧から購入までどのように商品と関わっているかを分析したい場合。

MCPを使用した解決策:

  1. 選択した期間の商品の詳細統計をリクエストします。

  2. 各段階(閲覧 → カート追加 → 注文 → 購入)のコンバージョンを分析します。

  3. コンバージョンが低い商品を特定し、最適化します。

コード例:

// Получение статистики воронки продаж
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. 検索表示の最適化

シナリオ: Wildberriesの検索での商品の表示を改善したい場合。

MCPを使用した解決策:

  1. 自社商品の検索クエリレポートをリクエストします。

  2. どのクエリで商品の順位が良いか、どのクエリで悪いかを分析します。

  3. 順位を改善するために商品カードを最適化します。

コード例:

// Получение отчета по поисковым запросам
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. 分析に基づく在庫管理

シナリオ: 販売データに基づいて倉庫の在庫レベルを最適化したい場合。

MCPを使用した解決策:

  1. 在庫と販売のレポートを定期的にリクエストします。

  2. 販売速度に基づいて最適な在庫レベルを計算します。

  3. 過剰在庫または不足在庫の商品を特定します。

コード例:

// Получение отчета по остаткам
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. 拡張CSVレポートの生成と分析

シナリオ: Excelやその他のツールでの詳細な分析用に詳細なデータを取得したい場合。

MCPを使用した解決策:

  1. MCPを介してCSVレポート生成タスクを作成します。

  2. 生成の完了を待ってレポートをダウンロードします。

  3. データを分析ツールにインポートして分析します。

コード例:

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

APIトークンの取得

MCPサーバーを介してWildberries APIを操作するには、APIトークンが必要です。取得方法は以下のとおりです:

  1. Wildberriesセラー個人アカウントにログイン

    seller.wildberries.ruにアクセスして認証します。

  2. API設定セクションに移動

    ログイン後、「設定」セクションに移動します(通常はメニューまたはプロフィールからアクセスできます)。

  3. API管理セクションに移動

    「API」または「APIアクセス」または「統合」セクションを見つけます。

  4. 新しいAPIトークンを作成

    • 「新しいトークンを作成」または同様のボタンをクリックします

    • トークンに必要なアクセス権限を選択します:

      • WB API MCPサーバーには以下が必要です:

        • 販売ファネルと検索クエリ用の分析カテゴリの権限

        • 広告統計用のプロモーションカテゴリの権限

    • トークンの名前を指定します(ご自身の利便性のため)

    • 必要に応じて有効期限を設定します(または無期限のままにします)

  5. トークンを生成して保存

    必要な情報を入力したら、「生成」または「作成」をクリックしてAPIトークンを生成します。

    重要: 必ずトークンをコピーして安全に保管してください!完全なトークンはセキュリティ上の理由から一度だけ表示されます。

トラブルシューティング

よくある問題

  1. 接続拒否:サーバーが起動しており、ポートが利用可能であることを確認してください。

  2. 認証エラー:Wildberries APIトークンが有効で、必要な権限を持っていることを確認してください。

  3. リクエスト頻度制限:サーバーはWildberries APIのリクエスト頻度制限を処理しますが、許容リクエスト数を超えた場合は待機が必要になる場合があります。

ログの表示

DockerまたはDocker Composeで起動する場合、ログはボリュームとしてマウントされたlogsディレクトリに保存されます。

実行中のDockerコンテナでログを表示するには:

docker logs wb-api-mcp

エラーコード

  • 401 - 認証エラー(APIトークンを確認してください)

  • 429 - リクエスト制限超過(しばらく待ってください)

  • 400 - 不正なリクエスト(リクエストパラメータを確認してください)

  • 403 - アクセス拒否(トークンの権限を確認してください)

Cloudflare Workersへのデプロイ

サーバーはCloudflare Workerとしてもデプロイできます(wrangler deployまたはGitHubからCloudflare Dashboardへの自動デプロイ経由)。Cloudflareは2026年から、アダプターcloudflare:nodeを通じてWorkers上でのExpressアプリケーションの実行を公式にサポートしています。これには2つのファイルが関与します:wrangler.jsonc(設定)とworker-entry.mjs(エントリポイントのラッパー)。npm start/Dockerによる通常起動ではこれらは使用されず、必要もありません。

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

要件: ビルド環境のNode.js ≥20(Cloudflare Dashboardでは.nvmrcによって自動設定されるか、Settings → BuildのNODE_VERSION変数で設定されます)。

Docker/通常のNodeホスティングと比較した重要な制限事項:

  • レート制限(express-rate-limit)はカウンターをプロセスのメモリ内に保存します。Workersではアイソレートが定期的に再作成されるため、リクエスト制限は常時稼働のサーバーよりも頻繁にリセットされる可能性があります。本番環境で厳格な制限を行うには、express-rate-limitの代わりに(または併用して)プラットフォームレベルのCloudflare Rate Limiting Rulesを推奨します。

  • リクエストあたりのCPU時間はCloudflareのプラン(特に無料プラン)によって制限されます。/api/evirma/import/*による大きな.xlsxファイルの解析は、非常に大きなエクスポートで制限に達する可能性があります。

  • アップロードされたファイル(multer)はリクエストのメモリ内でのみ処理されます。これはDockerでも既に同様であり、ここでは何も変わりません。

このような制約なしに完全に予測可能なNodeランタイムが必要な場合は、通常のDockerデプロイ(上記参照)を使用してください。サーバーは元々そのために書かれたものです。

セキュリティと本番運用

  • 本番環境ではHTTPSが必須です。 サーバー自体はTLSを終端しません。reverse-proxy(nginx、Caddy、Cloudflare Tunnelなど)の背後に配置してください。そうしないとapi-keyトークンが平文で送信されます。

  • トークンはサーバー上に一切保存されません。 クライアントが各リクエストでapi-keyヘッダーにトークンを渡し、Wildberries APIへのプロキシにのみ使用されます。

  • /healthは認証を必要としません。 モニタリングおよびDocker/Kubernetesのヘルスチェック用であり、機密データは返しません。

  • レート制限 — 組み込みのRATE_LIMIT_MAX(1分間に1つのIPからのリクエスト数制限)は、Wildberries APIへの偶発的なバーストリクエストから保護します。

  • 依存関係とコードの自動スキャン — Dependabot(npm/Docker/Actions)とCodeQLは毎週および各PR時に実行されます(.github/を参照)。

  • コンテナは非特権ユーザー(appuser)で実行され、rootでは実行されません。

  • ファイルのアップロード(/api/evirma/import/keywords-report)はサイズ15MBと拡張子.xlsx/.xlsに制限されています。ファイルはメモリ内でのみ処理されます(ディスクには保存されません)。

Related MCP Connectors

Related MCP Servers

  • A
    license
    B
    quality
    B
    maintenance
    Wildberries Seller API MCP server providing 15 tools for managing products, prices, stocks, orders, sales, warehouses, supplies, statistics, feedbacks, and ABC analysis with built-in rate limiting and 409 penalty protection.
    30
    27 npm
    16
    MIT
  • F
    license
    Not graded
    quality
    D
    maintenance
    MCP server that turns Wildberries marketplace into a toolkit for LLM agents, enabling product search, detailed card inspection, price history, reviews, and cross-product comparison.
    -
  • A
    license
    A
    quality
    D
    maintenance
    MCP server for Wildberries Seller API enabling management of products, orders, supplies, analytics, advertising, and finance through natural language commands.
    3
    2
    MIT