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