marketplaces-mcp-ru — Wildberries & Ozon Seller APIs

marketplaces-mcp-ru: Wildberries, Ozon, Яндекс Маркет и Авито в вашем ИИ-ассистенте

🇬🇧 English version

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

Зачем

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

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

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

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

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

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

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

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

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

Установка

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

1. Claude Desktop в один клик (.mcpb). Возьмите marketplaces-mcp-ru-v<версия>.mcpb из GitHub Releases и дважды кликните — Claude Desktop сам поставит расширение и спросит ключи в окне настроек. Без терминала и без Gatekeeper. Один бандл поднимает WB + Ozon + Ozon Performance + Яндекс Маркет + Авито сразу.
2. Попросить своего ИИ (без терминала). Откройте Claude или Cowork и скажите: «установи marketplaces-mcp-ru». Агент проведёт по встроенному скиллу 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. Для разработчиков (npx / uvx). npx -y marketplaces-mcp-ru — та же строка, что в конфигах всех MCP-клиентов; Python ставить не нужно, запускалка с npm сама подтянет uv и нужную версию с PyPI. uvx marketplaces-mcp-ru запускает объединённый сервер прямо из PyPI; отдельные серверы — консольными командами wb-mcp / ozon-mcp / ozon-perf-mcp / yandex-mcp / avito-mcp. Ключи — через переменные окружения или те же *_add_cabinet из чата.
6. VS Code / Cursor в один клик. Кнопки «поставить» над этим текстом открывают редактор и прописывают uvx marketplaces-mcp-ru в его конфиг MCP; VS Code сразу спросит ключи, в Cursor их вписывают в открывшийся JSON.
7. Docker. docker run -i --rm -e WB_API_TOKEN=… -e OZON_CLIENT_ID=… -e OZON_API_KEY=… ghcr.io/ilyautov/marketplaces-mcp-ru — тот же объединённый сервер по stdio, без Python на машине. Этот образ и указан в MCP Registry как OCI-пакет. Для удалённого доступа добавьте -e MCP_TRANSPORT=http -e MCP_HTTP_HOST=0.0.0.0 -p 8000:8000: сервер поднимется на http://…:8000/mcp (Streamable HTTP). Своей авторизации у HTTP-режима нет, закрывайте его прокси или файрволом.

Установщик копирует приложение в стабильную папку (~/.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-ключи. Яндекс Маркет: partner.market.yandex.ru → Настройки → Доступ к API (Api-Key). Авито: avito.ru → Для бизнеса → Интеграции → API (client_id + client_secret). Ключи хранятся в ~/.marketplace-mcp/cabinets.json локально (chmod 600), в репозиторий и в чат не попадают. Можно подключить несколько магазинов и переключаться между ними прямо из чата (*_add_cabinet / *_use_cabinet).

Проверка после установки: одна команда показывает по всем пяти серверам, сколько инструментов и методов загрузилось, найдены ли ключи и где (кабинет / env), а с --live делает по одному реальному read-вызову в каждый кабинет.

python3 serve.py doctor --live          # из клона
uvx marketplaces-mcp-ru doctor --live   # из PyPI
npx -y marketplaces-mcp-ru doctor --live  # то же через npm, без Python

Код возврата 0 означает, что все настроенные кабинеты ответили. Секреты в вывод не попадают.

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

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

• 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 Seller, Ozon Performance, Яндекс Маркет, Авито) на общем ядре. Вместо «один инструмент на каждый эндпоинт» (это 300+ инструментов, в которых агент теряется) сделано иначе: 8 универсальных мета-инструментов поверх каталога методов. Полное покрытие API при компактной поверхности.

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

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

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

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

Каталог собран 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
Яндекс Маркет (Partner API)	yandex_mcp/endpoints.yaml	165	29
Авито (API для бизнеса)	avito_mcp/endpoints.yaml	64	8

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

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

Яндекс Маркет и Авито (добавлены в 0.5.0):

Область	Яндекс Маркет	Авито
Заказы	заказы FBS / DBS / Экспресс, статусы, возвраты, отгрузки	заказы Авито Доставки, подтверждение, трек-номера, маркировка
Товары и остатки	каталог, карточки, остатки по складам, скрытые товары	объявления, остатки в объявлениях, автозагрузка
Цены	цены, карантин цен, акции, рекомендации	цена объявления
Отзывы и чаты	отзывы, вопросы, чаты с покупателями	рейтинг, отзывы и ответы, мессенджер
Аналитика	статистика заказов и товаров, 27 отчётов, индекс качества	просмотры и контакты, расходы, звонки
Продвижение	буст продаж, ставки	услуги продвижения, BBIP
Аналитика	воронка продаж, отчёты	аналитические отчёты, оборачиваемость

Полный список секций покажет *_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 / pageToken / page)
  entities.py        нормализация сущностей (товары, заказы и т.д.)
  workflows.py       движок пошаговых сценариев
  tools.py           регистрация мета-инструментов в MCP
  transport.py       выбор транспорта: stdio (по умолчанию) или Streamable HTTP
  doctor.py          диагностика: инструменты, каталоги, ключи, живой пинг
  errors.py          единый формат ошибок
wb_mcp/              сервер WB: server.py + endpoints.yaml + workflows.yaml
ozon_mcp/            сервер Ozon: server.py + endpoints.yaml + perf_endpoints.yaml + workflows.yaml
ozon_perf_mcp/       сервер Ozon Performance (реклама, OAuth2)
yandex_mcp/          сервер Яндекс Маркета: server.py + endpoints.yaml + workflows.yaml
avito_mcp/           сервер Авито: server.py + endpoints.yaml + workflows.yaml (OAuth2)
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 серверов: 21 тул для wb, 21 для ozon, 16 для ozon-perf, 22 для yandex, 26 для avito
python3 serve.py wb --selfcheck
python3 serve.py ozon --selfcheck
python3 serve.py ozon-perf --selfcheck
python3 serve.py yandex --selfcheck
python3 serve.py avito --selfcheck

# всё сразу: инструменты, каталоги, ключи, живой пинг кабинетов
python3 serve.py doctor --live

# образ для MCP Registry / удалённого запуска
docker build -t marketplaces-mcp-ru .
docker run --rm marketplaces-mcp-ru doctor

Транспорт. По умолчанию stdio, как ждут Claude Desktop, Cursor, Codex и Claude Code. MCP_TRANSPORT=http переключает любой из серверов (и объединённый) на Streamable HTTP: MCP_HTTP_HOST (по умолчанию 127.0.0.1), MCP_HTTP_PORT (8000), MCP_HTTP_ALLOWED_HOSTS — список допустимых заголовков Host через запятую, защита от DNS-rebinding при публикации наружу. Аутентификации у HTTP-режима нет: кто дотянулся до порта, тот работает с вашими ключами. Держите его на localhost или за прокси. Cómo está estructurado y crece el catálogo. endpoints.yaml se construye schema-driven a partir de los OpenAPI specs oficiales: ingest_specs.py (WB) y ingest_ozon.py (Ozon) traen las rutas, derive_pagination.py y fix_items_path_from_examples.py configuran la paginación y items_path, sync_swagger.py descarga los specs actualizados. El registro de cada método describe operation_id, el método, el host, la ruta, el scope, el nivel de riesgo y la paginación. La importación es idempotente y aditiva: los niveles de riesgo y las descripciones curadas no se sobrescriben. validate_items_path.py es un validador en vivo (para ejecutar localmente con tus propias claves), package_release.py genera un zip versionado limpio, smoke_mcp.py es una prueba de humo.

Qué es especialmente útil enviar:

• Verificación en producción de los verbos HTTP. Las rutas de los métodos importados son confiables, pero los verbos no: la prueba en vivo encontró «GET» que en realidad eran POST (405). Corrige */endpoints.yaml y adjunta la evidencia: el código de respuesta o un enlace al documento.
• Nuevos escenarios en */workflows.yaml: recetas paso a paso con interpretación y errores típicos, cada paso verificado contra el catálogo.
• Ajuste de la clasificación de seguridad, si un método está marcado demasiado permisivo o demasiado estricto.

Las reglas completas están en CONTRIBUTING.md. Antes del PR, ejecuta las pruebas offline y --selfcheck de todos los servidores; si cambiaste el número de métodos o herramientas, actualiza las cifras en el README.

Seguridad del repositorio. Las guías para personas y agentes están en AGENTS.md. Los secretos viven solo localmente: .env, cabinets.json, las claves y los certificados están protegidos por .gitignore, y el pre-commit ejecuta scripts/security/forbid_sensitive_files.py y scan_mcp_config.py. Que un método mutante no entre al catálogo con nivel read lo garantiza la prueba test_safety_catalog.py: la compilación falla en PUT, PATCH o DELETE con la marca read. El archivo .mcp.json se rastrea a propósito, es el manifiesto del plugin sin secretos.

Preguntas frecuentes

¿Necesito saber programar? No. Hay una instalación «pídele a tu IA» y una instalación con doble clic. pip install y editar JSON no son necesarios, las dependencias se instalan solas, solo necesitas tu clave de API.

¿Es seguro? ¿A dónde van las claves? El servidor funciona donde está tu agente, localmente. Las claves están en ~/.marketplace-mcp/cabinets.json (chmod 600), no llegan al repositorio ni al chat. Cualquier cambio en el panel (precio, stock) ocurre solo con tu confirmación.

¿En qué es mejor que los parsers y los bots de navegador? Es la Seller API directa por token, no un análisis de páginas web: no hay captcha, no hay bloqueos, los datos llegan estructurados. Además, hay protección contra cambios accidentales de precio o stock.

¿Es gratis? Sí, código abierto bajo licencia MIT. Tómalo, haz fork, mejóralo.

¿Funciona con Yandex Market y Avito? Sí, desde la versión 0.5.0. Yandex Market se conecta con Api-Key del panel de socio (Partner API: pedidos, productos, stock, precios, informes, chats, índice de calidad). Avito — con el par client_id / client_secret de la sección «Integraciones» (pedidos de Avito Delivery, stock y precios de anuncios, estadísticas, reseñas, mensajería, promoción). Los servidores yandex-mcp y avito-mcp funcionan tanto por separado como dentro del combinado.

¿Qué es MCP y para qué le sirve a un vendedor? MCP (Model Context Protocol) es un estándar abierto por el cual un asistente de IA conecta herramientas externas. Este proyecto es un servidor MCP para marketplaces: convierte las APIs de Wildberries, Ozon, Yandex Market y Avito en herramientas que el agente invoca solo, según tu pregunta en ruso.

Advertencias

Verifica con la documentación en vivo de los marketplaces:

• WB Authorization: el servidor envía el token crudo sin el prefijo Bearer (confirmado en la práctica). Si la autorización falla, revisa esto primero.
• Métodos importados de las especificaciones: las rutas son confiables, los verbos HTTP no siempre. La prueba en vivo encontró métodos marcados como GET que en realidad eran POST (respuesta 405). Trata estos registros como un mapa de exploración: confirma el verbo y el cuerpo según la documentación o invoca a través de call_raw. El núcleo curado (7 categorías WB, 4 secciones Ozon) y el conjunto verificado en vivo son confiables.
• Ozon varía entre versiones (list v3, attributes v4, prices v5). Ante un 404, verifica la versión; ingest_ozon.py realinea las rutas.
• Ozon Performance: por ahora es un artefacto de catálogo más el envoltorio OAuth según la documentación. El contrato del endpoint de token no se ha verificado en vivo, se necesitan credenciales publicitarias.
• Yandex Market y Avito (nuevo en 0.5.0): los catálogos se crearon a partir de documentos OpenAPI oficiales, las herramientas tipadas están escritas según la especificación, pero aún no se ha hecho una ejecución en vivo con paneles reales. Puede haber errores en los nombres de los campos, describe_method y call_raw ayudarán a corregir la solicitud en el momento.
• El panel oculta las variables de entorno. El panel activo en cabinets.json tiene prioridad sobre el entorno. Ante un 401 inexplicable o «Client-Id should be positive integer»: revisa primero este archivo.

Qué no es esto

Es una herramienta para un agente de IA, no un servicio en línea «con un clic» ni un reemplazo para un analista. La decisión que cambia precios, stock o dinero siempre queda en tus manos; la protección solo evita que ocurra accidentalmente. El proyecto está en fase alpha: instálalo, pruébalo con tus datos, experimenta. Si encuentras un problema, abre un issue (sin claves reales ni datos del panel).

La arquitectura tomó ideas sólidas de marketplace-MCP maduros (catálogo schema-driven, verificación de seguridad, formato de error unificado, auto-paginación), pero está implementada con código propio, sin dependencia de bibliotecas de terceros.

Licencia

MIT.