mcp-server-wildberries

mcp-name: io.github.dontsovcmc/wildberries

MCP-сервер для Wildberries Seller API — товары, заказы, поставки, аналитика, реклама, финансы.

235 действий, покрывающих все разделы WB API.

Построен по официальной документации Wildberries API.

Архитектура

Сервер использует паттерн search + execute — вместо 235 отдельных инструментов предоставляет 3:

Инструмент	Описание
wb_search	Поиск действий по описанию на естественном языке
wb_execute	Выполнение действия по ID
wb_execute_file	Выполнение действия со скачиванием файла

Это экономит токены в контексте LLM — схемы 3 инструментов вместо 235.

Как это работает

LLM: wb_search("cancel fbs order")
→ [{"id": "fbs-order-cancel", "params_schema": {"order_id": "int"}, ...}]

LLM: wb_execute("fbs-order-cancel", '{"order_id": 12345}')
→ {"status": "ok"}

Настройка

1. Получите API-токен Wildberries

Откройте Личный кабинет продавца WB → Настройки → Доступ к API → Создать токен.

2. Установите и подключите

macOS / Linux

Установка:

pip install mcp-server-wildberries

Подключение к Claude Code (токен в командной строке):

claude mcp add wildberries -e WB_TOKEN=ваш-токен -- mcp-server-wildberries

Подключение к Claude Code (токен из .env файла):

source .env && claude mcp add wildberries -e WB_TOKEN -- mcp-server-wildberries

Удаление MCP-сервера:

claude mcp remove wildberries

CLI без Claude (токен в командной строке):

WB_TOKEN=ваш-токен mcp-server-wildberries ping

CLI без Claude (токен из .env файла):

source .env && mcp-server-wildberries ping

Windows

Установка:

pip install mcp-server-wildberries

Подключение к Claude Code (токен в командной строке):

set WB_TOKEN=ваш-токен && claude mcp add wildberries -e WB_TOKEN -- mcp-server-wildberries

Подключение к Claude Code (токен из .env файла):

for /f "tokens=1,2 delims==" %a in (.env) do set %a=%b
claude mcp add wildberries -e WB_TOKEN -- mcp-server-wildberries

Удаление MCP-сервера:

claude mcp remove wildberries

CLI без Claude (токен в командной строке):

set WB_TOKEN=ваш-токен && mcp-server-wildberries ping

CLI без Claude (токен из .env файла):

for /f "tokens=1,2 delims==" %a in (.env) do set %a=%b
mcp-server-wildberries ping

Запуск через uvx (без установки)

Если не хотите устанавливать пакет глобально, используйте uvx — он скачает и запустит автоматически:

# Подключение к Claude Code
claude mcp add wildberries -e WB_TOKEN=ваш-токен -- uvx mcp-server-wildberries

# CLI
WB_TOKEN=ваш-токен uvx mcp-server-wildberries ping

Запуск через --mcp-config (на одну сессию)

Подключает сервер только на время одной сессии Claude, не сохраняя в настройки. Токен хранится в отдельном .env.mcp файле, а не в конфиге Claude.

Из JSON-строки:

claude --mcp-config '{"wildberries":{"command":"bash","args":["-c","source ~/.env.mcp && exec uvx mcp-server-wildberries"]}}'

Из файла:

claude --mcp-config ~/mcp-servers.json

Только указанные серверы, без сохранённых:

claude --strict-mcp-config --mcp-config ~/mcp-servers.json

Пример ~/mcp-servers.json:

{
  "wildberries": {
    "command": "bash",
    "args": ["-c", "source ~/.env.mcp && exec uvx mcp-server-wildberries"]
  }
}

Пример ~/.env.mcp:

WB_TOKEN=ваш-токен

Плюсы:

• Токены в отдельном файле .env.mcp, а не в настройках Claude
• Один файл mcp-servers.json на все проекты — легко делиться конфигом в команде
• --strict-mcp-config — запуск с точным набором серверов, без лишних
• Не засоряет глобальные настройки при экспериментах

Минусы:

• Сервер не сохраняется между сессиями — нужно указывать флаг при каждом запуске
• Длинная команда запуска, если без файла

После подключения перезапустите Claude Code.

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

Переменная	Обязательная	По умолчанию	Описание
WB_TOKEN	Да	—	API-токен Wildberries (JWT)
WB_TIMEOUT	Нет	30	Таймаут HTTP-запросов к API (секунды)
WB_FILE_TIMEOUT	Нет	60	Таймаут скачивания файлов (секунды)

Доступные действия (235)

Все действия доступны через wb_search → wb_execute. Подробное описание каждого действия — в документации по разделам:

Домен	Кол-во	Описание
general	9	Ping, информация о продавце, пользователи
content	18	Категории, карточки товаров, теги, бренды
fbs_orders	31	FBS-заказы, стикеры, поставки, пропуска, метаданные
dbw_orders	16	DBW-заказы (доставка WB)
dbs_orders	20	DBS-заказы (дропшиппинг)
pickup_orders	16	Самовывоз (click & collect)
fbw_supplies	7	FBW-поставки на склад WB
advertising	26	Рекламные кампании, ставки, статистика
communications	22	Вопросы, отзывы, чаты
tariffs	5	Комиссии, тарифы на доставку
analytics	17	Воронка продаж, поисковые запросы, остатки
reports	24	Заказы, продажи, остатки, маркировка
finance	12	Баланс, отчёты, эквайринг, документы
wbd	12	Цифровые товары, ключи активации

Примеры поиска

wb_search("новые заказы fbs")
wb_search("баланс")
wb_search("отзывы", domain="communications")
wb_search("download report", domain="reports")

CLI

# MCP-сервер (по умолчанию, без аргументов)
mcp-server-wildberries

# Все доступные команды
mcp-server-wildberries --help

# Справка по конкретной команде
mcp-server-wildberries fbs-orders --help

# Примеры команд
mcp-server-wildberries ping
mcp-server-wildberries seller-info
mcp-server-wildberries fbs-orders-new
mcp-server-wildberries tariff-commissions
mcp-server-wildberries fbs-orders --date-from 2025-01-01 --limit 10
mcp-server-wildberries advert-campaign-rename 12345 "Новое название"
mcp-server-wildberries analytics-csv-download dl_abc report.csv

# Версия
mcp-server-wildberries --version

Пример

$ WB_TOKEN=ваш-токен mcp-server-wildberries ping
{"TS": "2026-05-06T18:06:30Z", "Status": "OK"}

$ WB_TOKEN=ваш-токен mcp-server-wildberries seller-info
{"name": "ИП Иванов И.И.", "sid": "...", "tradeMark": "MyBrand"}

Pydantic-модели

Модели параметров доступны как отдельная библиотека для использования в своих Python-программах:

pip install mcp-server-wildberries

from mcp_server_wildberries.models import FbsOrdersParams, SubjectsListParams

params = FbsOrdersParams(date_from="2025-01-01", limit=50)
# params.model_dump() → {"date_from": "2025-01-01", "date_to": "", "limit": 50, ...}

62 Pydantic-модели покрывают параметры всех 235 действий. Полный список — в src/mcp_server_wildberries/models.py.

Разработка

pip install -e ".[test]"
ruff check src/ tests/
pytest tests/ -v

Лицензия

MIT