Wildberries MCP Server

MCP server для работы с API Wildberries продавца через stdio.

Сервер ориентирован на v1 сценарии:

• создание карточек товаров WB с характеристиками, размерами и SKU;
• загрузка медиа по прямым URL;
• чтение и установка цен;
• чтение и обновление остатков FBS на существующих складах продавца;
• lookup предметов, характеристик и справочников WB.

Требования

• Node.js 20+ (24.x проверен локально)
• pnpm 10+
• API-токен WB с категориями:
  • Content
  • Prices and Discounts
  • Marketplace

Установка

pnpm install
pnpm build

Для разработки:

pnpm dev

Установка в Codex

В проект уже добавлены:

• .codex-plugin/plugin.json
• .mcp.json
• npm bin entrypoint wildberries-mcp-server

Практически это даёт два способа установки.

Вариант 1. Как Codex plugin

Если Codex умеет ставить plugin из git-репозитория, достаточно установить этот репозиторий как plugin. Внутри plugin уже есть .mcp.json, который запускает сервер так:

npx -y wildberries-mcp-server

После установки plugin пользователю останется только задать WB_API_TOKEN.

Вариант 2. Как обычный MCP server через npx

Можно подключить сервер напрямую в MCP-конфиг:

{
  "mcpServers": {
    "wildberries": {
      "command": "npx",
      "args": ["-y", "wildberries-mcp-server"],
      "env": {
        "WB_API_TOKEN": "your-wb-token",
        "WB_API_LOCALE": "ru"
      }
    }
  }
}

В этом варианте ручная установка зависимостей не нужна: npx сам скачает пакет.

Переменные окружения

• WB_API_TOKEN — обязательный токен Wildberries
• WB_API_LOCALE — ru | en | zh, по умолчанию ru
• WB_API_TIMEOUT_MS — таймаут HTTP-запроса, по умолчанию 30000
• WB_LOG_LEVEL — debug | info | warn | error, по умолчанию info

Пример MCP-конфига

{
  "mcpServers": {
    "wildberries": {
      "command": "node",
      "args": [
        "C:/Users/Behrooz/Desktop/Wildberries MCP/dist/index.js"
      ],
      "env": {
        "WB_API_TOKEN": "your-wb-token",
        "WB_API_LOCALE": "ru"
      }
    }
  }
}

Доступные tools

• wb_token_info — декодирует токен и показывает его тип/права
• wb_ping — проверяет common, content, prices, marketplace
• wb_subjects_search — поиск предметов WB
• wb_characteristics_get — характеристики предмета по subjectId
• wb_content_directory_lookup — бренды, цвета, страны, сезоны, НДС, ТН ВЭД, пол
• wb_card_create — создание карточек WB с raw payload
• wb_cards_list — список карточек и размеров
• wb_card_errors_list — ошибки асинхронного создания/обновления карточек
• wb_media_upload — привязка изображений/видео по URL через /content/v3/media/save
• wb_media_file_upload — прямая загрузка локального файла через /content/v3/media/file
• wb_prices_get — чтение цен
• wb_prices_set — установка цен и скидок
• wb_prices_upload_status — статус/детали uploadID по ценам
• wb_size_prices_get — чтение цен по размерам
• wb_size_prices_set — установка цен по размерам
• wb_warehouses_list — существующие склады продавца
• wb_inventory_get — чтение остатков FBS по warehouseId и chrtId
• wb_inventory_update — обновление остатков FBS

Как работать с карточками

Практический порядок:

1. Найти предмет через wb_subjects_search
2. Получить характеристики через wb_characteristics_get
3. Добрать значения справочников через wb_content_directory_lookup
4. Создать карточку через wb_card_create
5. Проверить ошибки очереди через wb_card_errors_list
6. Получить nmID и chrtID через wb_cards_list
7. Загрузить медиа, цены и остатки

Важно:

• WB создаёт карточки асинхронно.
• После создания карточки синхронизация может занимать до 30 минут.
• До завершения синхронизации цены и остатки могут не применяться.

Пример payload для wb_card_create

Tool принимает payload в формате WB API почти без изменений. Можно передавать как объект/массив или как JSON-строку:

{
  "mode": "create",
  "payload": [
    {
      "subjectID": 1234,
      "variants": [
        {
          "vendorCode": "sku-001",
          "title": "Футболка базовая",
          "description": "Описание товара",
          "brand": "My Brand",
          "dimensions": {
            "length": 30,
            "width": 20,
            "height": 3,
            "weightBrutto": 0.25
          },
          "characteristics": [
            {
              "id": 14177449,
              "value": ["черный"]
            }
          ],
          "sizes": [
            {
              "techSize": "M",
              "wbSize": "46",
              "skus": ["1234567890123"]
            }
          ]
        }
      ]
    }
  ]
}

Команды

pnpm build
pnpm test
pnpm start

Источники

• https://dev.wildberries.ru/en/docs/openapi/api-information
• https://dev.wildberries.ru/en/docs/openapi/work-with-products