Ozon MCP Server

Ozon MCP Server

Управляйте магазинами Ozon прямо из чата с ИИ-ассистентом: цены, акции, реклама,заказы, возвраты, отзывы, финансы — 151 инструмент поверх Ozon Seller API иPerformance API.Для продавцов, у которых несколько магазинов: каждый вызов принимает shop_id,ключи хранятся зашифрованными на вашем сервере, наружу ничего не уходит.Отличие от прочих Ozon-MCP: покрыт не только Seller API, но и реклама, австроенная диагностика показывает, какие методы Ozon сломались, до того как этозаметит ассистент.

Торгуете ещё и на Wildberries? Есть такой же сервер для WB —wb-mcp-server.

Это личный рабочий инструмент автора: больше пяти месяцев ежедневной работы,порядка двадцати кабинетов, 151 инструмент. Обновляется он по мере собственнойнеобходимости автора — подробности в разделе«Обновления и поддержка».

Ты: Какие мои товары Ozon планирует затянуть в акцию?
Ты: Покажи расход по рекламным кампаниям за неделю и останови те, что тратят впустую.
Ты: У каких товаров индекс цены хуже, чем у конкурентов?
Ты: Ответь благодарностью на все новые отзывы с оценкой 5.

Что умеет

Полный нумерованный список с описанием каждого инструмента и его параметров —в docs/tools.md. Он сгенерирован из ozon_mcp/server.py(константа TOOLS) — то же самое отдаёт tools/list любому MCP-клиенту.

Быстрый старт

Вариант 1: одна команда, без Docker

Сервер работает по stdio — так его подключают Claude Desktop, Cursor, VS Code идругие MCP-клиенты. Ничего собирать не нужно:

uvx ozon-mcp-server

Или через pip:

pip install ozon-mcp-server
ozon-mcp

Конфигурация клиента (например, claude_desktop_config.json):

{
  "mcpServers": {
    "ozon": {
      "command": "uvx",
      "args": ["ozon-mcp-server"],
      "env": {
        "OZON_CLIENT_ID": "ваш Client-Id",
        "OZON_API_KEY": "ваш API-ключ",
        "DATA_DIR": "~/.ozon-mcp"
      }
    }
  }
}

DATA_DIR укажите на любой доступный для записи каталог — там хранятся магазины,ключи и статистика. По умолчанию используется /data (путь для Docker).

Вариант 2: Docker с веб-интерфейсом

Нужен, если хотите дашборд, диагностику Ozon API и удобное добавление магазиновчерез браузер. Пять команд:

git clone https://github.com/DeviceIngineering/ozon-mcp-server.git
cd ozon-mcp-server
cp .env.example .env               # для локальной сети можно оставить как есть
docker compose up -d --build       # соберёт образ и поднимет сервер на порту 8000
open http://localhost:8000/shops   # добавить магазин и ключи Ozon

Что делает каждый шаг:

• .env — все переменные необязательные. Ключи магазинов удобнее вводить ввеб-интерфейсе, а не здесь. Единственное, что стоит задать сразу, если сервервиден не только вам, — MCP_AUTH_TOKEN (сгенерировать: openssl rand -hex 32).
• docker compose up -d --build — собирает образ из Dockerfile, пробрасываетпорт 8000:8000 и создаёт том ozon_data для магазинов, ключей, статистики иистории диагностики. restart: unless-stopped поднимет контейнер послеперезагрузки машины.
• /shops — форма добавления магазина: shop_id (латиницей, им вы будетеоперировать в чате), название, Client-Id + Api-Key от Seller API иClient-Id + Client-Secret от Performance API. Кнопка «Проверить» делает живойзапрос к Ozon и говорит, приняты ли ключи.

После запуска:

Остановить: docker compose down (данные останутся в томе ozon_data).Логи: docker compose logs -f.

Без Docker

python3 -m venv .venv && source .venv/bin/activate
pip install .
DATA_DIR=./data PORT=8000 ozon-mcp-web

DATA_DIR по умолчанию /data — при локальном запуске обязательно переопределитеего на доступный каталог.

Установка в клиенты

Транспорт — SSE, адрес http://<host>:8000/sse. Поддержка SSE у клиентов разная:часть понимает его напрямую, части нужен мост mcp-remote. По файлу-инструкциина каждый клиент, с путями к конфигам под macOS, Linux, Windows и готовым JSON:

Самый короткий пример — Claude Code:

claude mcp add --transport sse ozon http://localhost:8000/sse \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

Сводка по клиентам и справочник по мосту — docs/README.md.

Мульти-магазин и безопасность

Кабинеты добавляются в веб-интерфейсе, каждый инструмент принимает обязательныйпараметр shop_id; узнать доступные — инструментом ozon_list_shops. В чате этовыглядит так: «покажи остатки в магазине alpha».

Главная выгода не в самом переключении, а в том, что стратегия пишется один рази раскатывается на все кабинеты: правило по ценам, по ответам на отзывы или поставкам применяется ко всем магазинам сразу — без перелогинивания в кабинеты и безкопирования ключей по конфигам разных клиентов.

Цена такого подхода — общий IP. Все кабинеты ходят в Ozon с одного адреса: с тогосервера, где стоит MCP. Лимиты Ozon считаются в том числе по адресу, и чем большекабинетов и чем активнее по ним работают стратегии, тем ближе суммарный поток кпорогу, за которым начинается throttling или блокировка.

• ограничения на число магазинов в коде нет;
• реальный потолок задаёт не сервер, а лимиты Ozon на один IP;
• порядка двадцати кабинетов — оценка автора, при которой поток остаётся вбезопасной зоне;
• дальше — разносить магазины по нескольким серверам с разными адресами.

Приближение к лимиту видно заранее, и как раз в веб-интерфейсе: растёт числонеудачных ping и предупреждений в диагностике, в статистике вызовов подскакиваетдоля ошибок. Отличить одно от другого тоже можно по дашборду: массовый throttlingвыглядит как одновременная деградация многих инструментов, поломка эндпоинта —как деградация одного.

Как хранятся ключи:

• при первом обращении в DATA_DIR создаётся .encryption_key — ключ Fernet;
• ключи магазинов шифруются им и лежат в DATA_DIR/shops.json;
• в веб-интерфейсе ключи показываются замаскированными (abc***xyz), присохранении маскированное значение не перезаписывает настоящее;
• в Docker всё это лежит в томе ozon_data; перенос на другую машину — копированиетома целиком, иначе потеряется ключ шифрования (см. DEPLOY.md).

Что важно знать про доступ:

• MCP_AUTH_TOKEN защищает только /sse. Токен передаётся заголовкомAuthorization: Bearer … либо параметром ?token=….
• Пустой MCP_AUTH_TOKEN = авторизация выключена. Так можно только в доверенной сети.
• Веб-интерфейс (/, /shops, /diagnostics) и /api/* токеном не закрыты:кто имеет сетевой доступ к порту, тот видит дашборд и может добавлять магазины.
• Не пробрасывайте порт 8000 в интернет напрямую. Для доступа извне — Tailscaleили VPN.
• HTTPS сервер не терминирует. Нужен внешний доступ по TLS — ставьте reverse proxy.

Веб-интерфейс: видно каждый вызов

У обычного MCP-сервера вызовы уходят в никуда: ассистент что-то сделал, а чтоименно, за сколько и с какой ошибкой — известно только ему. Здесь на каждый вызовесть строчка в журнале, а на каждый сломавшийся инструмент — отметка на дашборде.Для инструмента, который управляет реальными деньгами в магазине, это неукрашение, а условие доверия.

Статистика вызовов и история проверок собраны не на синтетике: больше пяти месяцевежедневной работы примерно на двадцати кабинетах. Оттуда же и список пойманныхизменений Ozon API в разделе про ограничения — он не выписан из документации, авзят из журнала деградаций.

Дашборд /

Скриншот — в начале страницы.

• Четыре счётчика сверху: всего вызовов, за сегодня, ошибок, средняя длительностьвызова в миллисекундах.
• Топ-10 инструментов: сколько раз вызывали, среднее время, сколько из нихзавершились ошибкой.
• Лента последних 50 вызовов: время, shop_id, имя инструмента, длительность,успех или ошибка и текст ошибки.
• Фильтр по магазину (/?shop=alpha) — те же цифры по одному кабинету.
• Сверху всплывают два предупреждения: о деградировавших инструментах и о том,что последняя проверка Ozon API нашла проблемы.

Магазины /shops

Кабинеты добавляются и удаляются прямо в браузере, без правки файлов иперезапуска контейнера. Кнопка «Проверить» делает живой запрос к обоим API(POST /api/shops/{shop_id}/test) — ключи проверяются сразу при добавлении, а нев момент первого рабочего вызова посреди задачи. Токены шифруются Fernet, ключшифрования лежит в DATA_DIR/.encryption_key, в интерфейсе ключи показываютсязамаскированными.

Диагностика /diagnostics

(на скриншоте — демо-магазин с заведомо неверными ключами, поэтому все пробы красные)

• По каждому магазину: заданы ли ключи, доступность хостов Ozon, 12 пробкатегорий Seller API, проверка ключей Performance API.
• Фоновая проверка каждые HEALTH_CHECK_INTERVAL_MIN минут (по умолчанию 30,0 — выключить) и кнопка «Проверить сейчас» для немедленного прогона(POST /api/diagnostics/run).
• История проверок: время, магазин, статус, число неудачных ping, число неудачныхпроб и текст предупреждений. В интерфейсе показываются последние 30 записей,в базе хранится до 1000 с автоматической ротацией.
• Те же данные доступны из чата инструментом ozon_diagnostics.

Детектор деградаций

Сервер сам замечает, что Ozon сломал или отключил эндпоинт, — не по документациии не по факту сорванной работы, а по собственной статистике. Инструмент, укоторого последние три вызова подряд завершились ошибкой, но раньше былиуспешные, попадает в список деградаций: там видно имя инструмента, времяпоследнего успешного вызова, число ошибок подряд и текст последней. На дашбордеэто красная плашка, на странице диагностики — таблица.

Практический смысл: изменение на стороне Ozon видно в тот день, когда онопроизошло, а не через неделю, когда обнаружится, что цены не обновлялись.Из чата тот же список отдаёт инструмент ozon_degradations.

JSON для внешнего мониторинга

Всё перечисленное снимается программно, а не только глазами:

Так сервер заводится в Zabbix, Uptime Kuma или в обычный curl по cron.

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

Один Docker-контейнер, внутри FastAPI-приложение, которое совмещает MCP-сервер ивеб-интерфейс.

• ozon_mcp/server.py — сам MCP-сервер. Список TOOLS описывает 151инструмент (имя, описание, JSON-схема аргументов), обработчик call_toolмаршрутизирует вызов в нужный метод клиента Ozon. Клиенты кешируются в пуле поshop_id, так что переключение между магазинами ничего не переподключает.
• ozon_mcp/client.py — два HTTP-клиента: OzonSellerClient (заголовкиClient-Id / Api-Key) и OzonPerformanceClient (токен client_credentials,живёт 30 минут и обновляется сам).
• ozon_mcp/app.py — FastAPI: эндпоинт /sse поверх SseServerTransport,проверка Bearer-токена, страницы дашборда, магазинов и диагностики, фоноваязадача health-проверки.
• ozon_mcp/settings.py — магазины и ключи: шифрование Fernet, маскированиедля UI, подхват ключей из переменных окружения как магазина default, миграциястарого однобазового settings.json в shops.json.
• ozon_mcp/diagnostics.py — пробы: пинг хостов Ozon плюс лёгкие реальныезапросы по 12 категориям Seller API и проверка ключей Performance API.
• ozon_mcp/stats.py — SQLite через aiosqlite: каждый вызов инструмента свременем и результатом, история health-проверок, расчёт деградаций.

Хосты, в которые ходит сервер:

Неочевидные места:

• Ставки и бюджеты рекламы Ozon отдаёт в микрорублях: 1000000 = 1 ₽.Не удивляйтесь семизначным числам.
• 403 на отзывах и вопросах — это не поломка, а отсутствие подпискиPremium Plus. Диагностика такие ответы ошибкой не считает.
• Ozon-ключи не содержат срока действия: истечение видно только по 401 в пробах.
• Асинхронная статистика рекламы — один отчёт одновременно, ≤10 кампаний, ≤62 дня;инструмент ждёт готовности отчёта до ~2 минут.
• Статусы заявок на поставку в API v3 — целые числа 1–8, а не строки.

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

Известные ограничения Ozon API (актуально на июнь 2026)

• Реклама: создание кампаний через API — только «Трафареты» (CPC); бюджеты иставки в микрорублях; официального метода узнать баланс рекламного кабинета нет.
• «Оплата за заказ»: ставки фиксированные (с февраля 2025), доступны тольковключение и выключение.
• Отзывы, вопросы и часть аналитики требуют подписку Premium Plus (ошибка code 7).
• Метрики воронки в ozon_analytics помечены Ozon как deprecated — для позицийв поиске используйте ozon_product_queries.
• /v3/finance/transaction/* отключаются 06.07.2026; замена уже встроена(ozon_finance_cash_flow, ozon_finance_accruals).
• ozon_product_stocks_by_warehouse использует v2, потому что v1 отключается 07.04.2026.
• Цифровые акты приёма-передачи FBS удалены Ozon 22.03.2026 — используется обычный акт.
• Метода «обновить ответ на отзыв» в Ozon API нет: ответ удаляется и создаётся заново.

Список собран не переписыванием справки: это журнал деградаций и пять месяцевежедневных вызовов, сверенные с документацией docs.ozon.ru по состоянию на июнь 2026.

Что изменилось в версии 2.0

Полная ревизия под Ozon API июня 2026 со сверкой живыми запросами: единый списоквозвратов, отмены v2, реализация v2, ship v4, supply-order v3, реальные ценовыестратегии и «Хочу скидку», собственные акции продавца, новая модель рекламы(трафареты CPC + «Оплата за заказ»), диагностика и детектор деградаций,авторизация MCP-эндпоинта.

Структура проекта

ozon-mcp-server/
├── docker-compose.yml   # порт 8000, том ozon_data
├── Dockerfile           # python:3.12-slim, uvicorn
├── DEPLOY.md            # деплой на отдельную машину, перенос данных
├── docs/                # подключение клиентов + справочник инструментов
└── ozon_mcp/
    ├── server.py        # MCP-сервер: 151 инструмент, мульти-магазин
    ├── client.py        # Seller API + Performance API
    ├── app.py           # FastAPI: SSE, веб, авторизация, health-loop
    ├── diagnostics.py   # пробы категорий, детектор деградаций
    ├── settings.py      # магазины и ключи (Fernet)
    ├── stats.py         # статистика вызовов и история проверок (SQLite)
    └── templates/       # dashboard, diagnostics, shops

Деплой на отдельную машину и перенос магазинов — DEPLOY.md.

Тот же сервер для Wildberries

wb-mcp-server — тот жеинструмент для второй площадки: одна архитектура, тот же веб-интерфейс сдашбордом и диагностикой, та же мульти-магазинность через shop_id, тот жетранспорт SSE и те же способы подключения к клиентам.

Практически это значит две вещи:

• Второй сервер ставится без нового обучения. Разобрались с одним — второйзапускается по этой же инструкции; отличаются порт (8001 против 8000) и наборинструментов.
• Держать оба на одной машине можно. Порты разные, данные лежат в разныхDocker-томах, конфликта нет. В клиенте это просто два MCP-сервера: ozon наhttp://localhost:8000/sse и wb на http://localhost:8001/sse.

Соседство на одном сервере не мешает и по лимитам: наружу оба ходят с одного IP,но Ozon и Wildberries считают лимиты каждый у себя — это разные площадки.Ограничение по числу кабинетов из раздела про мульти-магазин действует внутрикаждой площадки отдельно.

Обновления и поддержка

Ozon меняет API постоянно: эндпоинты добавляются, переименовываются и отключаются(в разделе про ограничения перечислено то, что уже поймано). Этот сервер —рабочий инструмент автора, и обновляется он по мере собственной необходимости:когда очередное изменение ломает что-то в его магазинах. Больше пяти месяцевежедневной работы — и коммиты появляются тогда, когда Ozon что-то ломает, а не порасписанию. Пауза между коммитами обычно означает, что всё работает. Плюс такогоподхода в том, что код проверяется реальной работой каждый день, а не выложен изабыт; минус — расписания и обязательств по срокам нет.

Если исправление нужно срочно — напишите на [email protected].Issues и pull request'ы тоже приветствуются и разбираются.

Лицензия

MIT — см. LICENSE.