marketplaces-mcp-ru 0.3.2

MCP servers for Wildberries and Ozon Seller APIs (schema-driven, safety-gated)

marketplaces-mcp-ru: Wildberries и Ozon в вашем ИИ-ассистенте

🇬🇧 English version

Подключает ИИ-ассистента (Claude, Cursor, Codex, Cowork и др.) напрямую к вашим кабинетам Wildberries и Ozon. Вы спрашиваете обычными словами, агент берёт продажи, остатки, цены, финансы и отзывы прямо из API маркетплейса, а не выдумывает цифры.

Зачем

Вы продаёте на двух площадках, а данные лежат в двух разных кабинетах. Продажи, остатки, цены, финансы, отзывы: всё руками, по очереди, через два браузера. Обычный ИИ-ассистент тут мало помогает. Либо ходит через браузер и спотыкается о капчу, либо называет цифры, которые звучат уверенно, но взяты из воздуха.

Этот проект решает задачу иначе. Он даёт ассистенту прямой доступ к Seller API обоих кабинетов:

• Цифры приходят из ответа Wildberries и Ozon, с указанием источника и полей. Не пересказ, не догадка.
• Перед тем как менять цену или остаток, агент просит подтверждение. Случайно «уронить цену в три раза» не получится.
• Никакого браузера и капчи: обращение идёт по токену кабинета напрямую.

Спросите обычными словами: «покажи продажи за неделю на обоих», «что пора дозаказать», «сравни мои цены с рынком». Агент подберёт нужный метод или готовый сценарий и проведёт по шагам.

⚠️ Версия alpha. Помогает с операционкой продавца, но это инструмент, а не замена аналитику. Проверенное вручную ядро (продажи, остатки, цены, финансы, отзывы) выверено на реальных кабинетах. Остальные методы импортированы из спецификаций и служат картой для разведки. Подробности в разделе Оговорки.

Что можно спросить

Просто пишите агенту в чат по-русски:

покажи продажи за неделю на WB и Ozon и сравни
что пора дозаказать, посчитай дни покрытия по остаткам и продажам
вытащи финотчёт реализации WB за прошлый месяц
какие товары на Ozon с красным индексом цены
собери отзывы ниже 4 звёзд за неделю и сгруппируй жалобы по товару
сделай ABC-анализ по выручке и покажи товары-хвост

Не знаете, с чего начать, скажите «что ты умеешь по моему кабинету». Агент покажет готовые сценарии: для Wildberries это пульс продаж, здоровье остатков, аудит цен, планировщик дозаказа, ABC-анализ, сводка отзывов; для Ozon: риск out-of-stock, анализ цен, юнит-экономика, синхронизация каталога, аудит контента и те же ABC и отзывы. Каждый сценарий это пошаговый рецепт с трактовкой результата и типичными ошибками.

Установка

Подробный гайд под любую аудиторию лежит в QUICKSTART.md. Несколько способов, результат один.

1. Claude Desktop в один клик (.mcpb). Возьмите marketplaces-mcp-ru-v<версия>.mcpb из GitHub Releases и дважды кликните — Claude Desktop сам поставит расширение и спросит ключи в окне настроек. Без терминала и без Gatekeeper. Один бандл поднимает WB + Ozon + Ozon Performance сразу.
2. Попросить своего ИИ (без терминала). Откройте Claude или Cowork и скажите: «установи WB + Ozon MCP». Агент проведёт по встроенному скиллу install-skill/. В песочнице Cowork финальный клик остаётся за вами; в Claude Code установка проходит полностью сама.
3. Скачать и кликнуть. Возьмите marketplaces-mcp-ru-v<версия>.zip из GitHub Releases, распакуйте, дважды кликните install.command (macOS) или install.bat (Windows), вставьте ключи. На macOS при первом запуске: правый клик → «Открыть» → «Открыть» (так обходится Gatekeeper для скачанного файла).
4. Через терминал. git clone https://github.com/ilyautov/marketplaces-mcp-ru, затем python3 install.py --client <ваш-клиент>.
5. Для разработчиков (uvx). uvx marketplaces-mcp-ru запускает объединённый сервер прямо из PyPI; отдельные серверы — консольными командами wb-mcp / ozon-mcp / ozon-perf-mcp. Ключи — через переменные окружения или те же *_add_cabinet из чата.

Установщик копирует приложение в стабильную папку (~/.marketplace-mcp/app) и привязывает конфиг туда, так что исходную папку потом можно перемещать или удалять, ничего не сломается. Ни pip install, ни ручной правки JSON: зависимости ставятся сами при первом запуске. От вас нужны только ключи. Поддерживается 4 клиента через --client: claude-desktop и opencode получают готовый конфиг, claude-code и codex получают готовые команды mcp add.

Где взять ключи. Wildberries: seller.wildberries.ru → Настройки → Доступ к API. Ozon: seller.ozon.ru → Настройки → API-ключи. Ключи хранятся в ~/.marketplace-mcp/cabinets.json локально (chmod 600), в репозиторий и в чат не попадают. Можно подключить несколько магазинов и переключаться между ними прямо из чата (*_add_cabinet / *_use_cabinet).

Проверка после установки:

python3 serve.py ozon --selfcheck

Безопасность

Ключ кабинета двигает цены, остатки и деньги, поэтому каждый метод заранее размечен по уровню риска:

• read: чтение, выполняется сразу;
• write: изменение, требует confirm_write=true;
• destructive: удаление, требует confirm_write=true и i_understand_this_modifies_data=true.

Проверка работает локально, наружу без подтверждения ничего не уходит. Что метод-мутация случайно не пометится как read, проверяет тест в CI (test_safety_catalog.py): сборка падает, если в каталог попадёт PUT, PATCH или DELETE с уровнем read. Дополнительно call_method подстраховывается на лету: даже устаревшая пометка read на мутирующем запросе не опустит проверку ниже write.

Подробнее в SECURITY.md. О найденной уязвимости пишите на [e-mail] с темой SECURITY: marketplaces-mcp-ru, без публичного issue.

Как это устроено

Под капотом два MCP-сервера (Wildberries и Ozon) на общем ядре. Вместо «один инструмент на каждый эндпоинт» (это 300+ инструментов, в которых агент теряется) сделано иначе: 8 универсальных мета-инструментов поверх каталога методов. Полное покрытие API при компактной поверхности.

ваш ИИ-агент
      │
      ▼
 8 мета-инструментов  ──►  каталог (endpoints.yaml)  ──►  общее ядро
 search / describe /                                      клиент · safety · ошибки
 call / call_raw /                                        пагинация · реестр
 fetch_all / ...                                                │
 + типизированные инструменты (wb_get_sales, …)                 ▼
                                            Wildberries / Ozon HTTPS API

Мета-инструменты одинаковы на обоих серверах (префикс wb_ или ozon_):

Инструмент	Что делает
*_check_auth	Проверяет наличие ключей (секреты не печатает)
*_search_methods	Ищет метод по-русски или по-английски
*_describe_method	Полное описание: метод, хост, путь, scope, уровень риска, лимит, ссылка на доку
*_call_method	Вызывает любой метод каталога через проверку безопасности
*_call_raw	Вызывает любой путь, даже которого ещё нет в каталоге (полное покрытие)
*_fetch_all	Авто-пагинация (offset / last_id / cursor / date-курсор WB)

Плюс типизированные инструменты для частых задач (wb_get_sales, wb_get_stocks, ozon_get_products, ozon_get_prices и др.) и инструменты управления кабинетами.

Каталог собран schema-driven из официальных OpenAPI-спецификаций:

Каталог	Файл	Методов	Секций
Wildberries	wb_mcp/endpoints.yaml	307	70
Ozon Seller	ozon_mcp/endpoints.yaml	441	67
Ozon Performance (реклама)	ozon_mcp/perf_endpoints.yaml	45	6

Ядро (продажи, остатки, цены, финансы, отзывы) выверено вживую; остальное импортировано из спецификаций, а call_raw достаёт то, чего ещё нет в каталоге. Что покрыто по бизнес-областям:

Область	Wildberries	Ozon
Продажи и заказы	продажи, заказы, сборочные задания FBS / DBS / DBW / Самовывоз	заказы FBO / FBS, отправления, возвраты
Остатки и склады	остатки, склады продавца, поставки FBS	остатки по складам, FBO / FBS, аналитика остатков
Цены и скидки	цены и скидки, календарь акций	цены, стратегии ценообразования, акции
Финансы	финотчёт реализации, баланс	транзакции, начисления, реализация, компенсации
Контент и карточки	карточки, категории, характеристики, медиа	товары, атрибуты, категории, сертификаты
Отзывы и вопросы	отзывы, вопросы	отзывы (нужен Premium Plus), вопросы и ответы
Реклама	управление кампаниями, статистика	Performance API (отдельный сервер)
Аналитика	воронка продаж, отчёты	аналитические отчёты, оборачиваемость

Полный список секций покажет *_list_sections прямо в чате, точечный поиск делает wb_search_methods("остатки").

Разработка

Раздел для тех, кто хочет покопаться в коде, выверить методы боем или прислать PR.

Структура. Вся общая логика живёт в core/, серверы это тонкие обёртки над ней:

core/                общее ядро обоих серверов
  client.py          HTTPS-клиент (хосты, заголовки, ретраи)
  credentials.py     загрузка ключей из cabinets.json / env
  safety.py          гейт read / write / destructive
  registry.py        загрузка и индексация каталога endpoints.yaml
  paginate.py        авто-пагинация (offset / last_id / cursor / date)
  entities.py        нормализация сущностей (товары, заказы и т.д.)
  workflows.py       движок пошаговых сценариев
  tools.py           регистрация мета-инструментов в MCP
  errors.py          единый формат ошибок
wb_mcp/              сервер WB: server.py + endpoints.yaml + workflows.yaml
ozon_mcp/            сервер Ozon: server.py + endpoints.yaml + perf_endpoints.yaml + workflows.yaml
scripts/             сборка каталогов, валидация, релиз
tests/               офлайн-тесты (токены не нужны)

Локальный запуск и тесты. Нужен Python 3.10+. Зависимости (mcp, httpx, pyyaml) serve.py ставит сам в локальный .venv при первом запуске.

git clone https://github.com/ilyautov/marketplaces-mcp-ru.git
cd marketplaces-mcp-ru

# офлайн-тесты, ключи не нужны — все офлайн-тесты зелёные
env -u OZON_CLIENT_ID -u OZON_API_KEY -u WB_API_TOKEN python3 -m pytest tests/ -q

# selfcheck серверов: отдаёт 19 тулов для wb, 19 для ozon, 14 для ozon-perf
python3 serve.py wb --selfcheck
python3 serve.py ozon --selfcheck
python3 serve.py ozon-perf --selfcheck

Как устроен и растёт каталог. endpoints.yaml собирается schema-driven из официальных OpenAPI-спеков: ingest_specs.py (WB) и ingest_ozon.py (Ozon) тянут пути, derive_pagination.py и fix_items_path_from_examples.py настраивают пагинацию и items_path, sync_swagger.py подтягивает свежие спеки. Запись каждого метода описывает operation_id, метод, хост, путь, scope, уровень риска и пагинацию. Импорт идемпотентный и аддитивный: курированные уровни риска и описания не перетираются. validate_items_path.py это live-валидатор (гонять локально на своих ключах), package_release.py собирает чистый версионный zip, smoke_mcp.py это дымовой тест.

Что особенно полезно прислать:

• Боевую выверку HTTP-глаголов. Пути у импортированных методов надёжны, а глаголы нет: live-проба находила «GET», которые на деле POST (405). Поправьте */endpoints.yaml и приложите доказательство: код ответа или ссылку на доку.
• Новые сценарии в */workflows.yaml: пошаговые рецепты с трактовкой и типичными ошибками, каждый шаг сверяется с каталогом.
• Уточнение safety-классификации, если метод размечен слишком мягко или строго.

Полностью правила в CONTRIBUTING.md. Перед PR прогоните офлайн-тесты и --selfcheck всех серверов; изменили число методов или тулов, поправьте цифры в README.

Безопасность репозитория. Гайдлайны для людей и агентов лежат в AGENTS.md. Секреты живут только локально: .env, cabinets.json, ключи и сертификаты закрыты .gitignore, а pre-commit прогоняет scripts/security/forbid_sensitive_files.py и scan_mcp_config.py. Что мутирующий метод не попадёт в каталог с уровнем read, держит тест test_safety_catalog.py: сборка падает на PUT, PATCH или DELETE с пометкой read. Файл .mcp.json отслеживается намеренно, это манифест плагина без секретов.

Частые вопросы

Нужно ли уметь программировать? Нет. Есть установка «попроси своего ИИ» и установка двойным кликом. pip install и правка JSON не нужны, зависимости ставятся сами, от вас только API-ключ.

Это безопасно? Куда уходят ключи? Сервер работает там же, где ваш агент, локально. Ключи лежат в ~/.marketplace-mcp/cabinets.json (chmod 600), в репозиторий и в чат не попадают. Любое изменение в кабинете (цена, остаток) происходит только с вашим подтверждением.

Чем это лучше парсеров и браузерных ботов? Это прямой Seller API по токену, а не разбор веб-страниц: нет капчи, нет блокировок, данные приходят структурированными. Плюс защита от случайного изменения цены или остатка.

Это бесплатно? Да, открытый код под лицензией MIT. Берите, форкайте, дорабатывайте.

Оговорки

Сверяйте с живой документацией маркетплейсов:

• WB Authorization: сервер шлёт raw-токен без префикса Bearer (подтверждено на практике). Если авторизация падает, проверьте это в первую очередь.
• Импортированные из спецификаций методы: пути надёжны, HTTP-глаголы не всегда. Live-проба находила методы, помеченные GET, которые на деле POST (ответ 405). Считайте такие записи картой для разведки: подтверждайте глагол и тело по докам или вызывайте через call_raw. Курированное ядро (7 категорий WB, 4 секции Ozon) и live-выверенный набор надёжны.
• Ozon дрейфует по версиям (list v3, attributes v4, prices v5). При 404 проверьте версию; ingest_ozon.py пере-выравнивает пути.
• Ozon Performance: пока каталог-артефакт плюс OAuth-обвязка по докам. Контракт токен-эндпоинта вживую не выверен, нужны рекламные креды.
• Кабинет затеняет переменные окружения. Активный кабинет в cabinets.json имеет приоритет над env. Необъяснимый 401 или «Client-Id should be positive integer»: первым делом проверьте этот файл.

Чем это не является

Это инструмент для ИИ-агента, а не онлайн-сервис «в один клик» и не замена аналитику. Решение, которое меняет цены, остатки или деньги, всегда остаётся за вами, защита лишь не даёт сделать это случайно. Проект на стадии alpha: ставьте, проверяйте на своих данных, экспериментируйте. Нашли проблему, заведите issue (без реальных ключей и данных кабинета).

Архитектура взяла сильные идеи зрелых marketplace-MCP (schema-driven каталог, проверка безопасности, единый формат ошибок, авто-пагинация), но реализована своим кодом, без зависимости от чужих библиотек.

Лицензия

MIT.