Ozon MCP Server

Ozon Seller API + Performance API: 151 tools for prices, promotions, advertising, orders, returns, finance and analytics across multiple seller accounts.

GitHubTry this MCPSponsored

Documentation

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.

Дашборд Ozon MCP Server

Что умеет

Группа	Инструментов	Что внутри
Акции и скидки	14	акции Ozon (список, кандидаты, вход/выход), собственные акции продавца, заявки «Хочу скидку»
Цены и ценовые стратегии	14	установка цен и минимальной цены, индекс цен, таймер минимальной цены, автостратегии по конкурентам
Реклама (Performance API)	22	кампании «Трафареты» (CPC), ставки и бюджеты, «Оплата за заказ» (CPO), статистика по товарам и дням
Товары	21	список и карточки, атрибуты, остатки, импорт и массовое обновление, медиа, архив, сертификаты
Заказы FBS и FBO	17	несобранные заказы, сборка (v4), этикетки, отмены, акты приёма-передачи, страна товара
Возвраты и отмены	10	единый список возвратов FBO+FBS, заявки rFBS с решением продавца, заявки на отмену
Отзывы, вопросы, чаты	13	отзывы и ответы, вопросы покупателей, переписка в чатах (v3)
Склады и отчёты	8	склады FBS, методы доставки, генерация и выгрузка отчётов
Финансы	7	баланс, транзакции, начисления, реализация, взаиморасчёты, движение денег
Категории, бренды, сертификаты	7	дерево категорий, атрибуты и их значения, сертификаты
Аналитика	5	аналитика по SKU, остатки и оборачиваемость, позиции товаров в поиске, топ поисковых запросов
Поставки FBO	4	заявки на поставку (v3), счётчики, таймслоты
Рейтинг	2	текущий рейтинг продавца и его история
Диагностика	2	самопроверка доступности Ozon API, детектор деградаций
Уведомления	2	подписки на push-вебхуки и справочник типов событий
Компания	2	данные продавца и тарифы
Магазины	1	список подключённых магазинов и их `shop_id`

Полный нумерованный список с описанием каждого инструмента и его параметров — в 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 и говорит, приняты ли ключи.

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

Адрес	Что это
`http://localhost:8000/`	дашборд: счётчики вызовов, ошибки, деградации
`http://localhost:8000/shops`	магазины и ключи
`http://localhost:8000/diagnostics`	диагностика Ozon API
`http://localhost:8000/api/health`	health-эндпоинт, JSON
`http://localhost:8000/sse`	эндпоинт MCP, его и указывают клиентам

Остановить: 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:

Клиент	SSE напрямую	Инструкция
Claude Code	да	docs/install-claude-code.md
Claude Desktop	нет, мост `mcp-remote`	docs/install-claude-desktop.md
Cursor	да	docs/install-cursor.md
Windsurf / Devin Desktop	да	docs/install-windsurf.md
VS Code (GitHub Copilot)	да	docs/install-vscode-copilot.md
Cline	да	docs/install-cline.md
Continue.dev	да	docs/install-continue.md
Zed	не подтверждено, рекомендуем мост	docs/install-zed.md
JetBrains AI Assistant / Junie	да	docs/install-jetbrains.md
Gemini CLI	да	docs/install-gemini-cli.md
OpenAI Codex CLI	нет, мост `mcp-remote`	docs/install-codex.md

Самый короткий пример — 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 для внешнего мониторинга

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

Эндпоинт	Что отдаёт
`GET /api/health`	статус сервиса, включена ли авторизация, последние проверки, деградировавшие инструменты
`GET /api/stats`	та же сводка, что на дашборде; `?shop=` — по одному магазину
`GET /api/diagnostics/{shop_id}`	полная живая диагностика магазина

Так сервер заводится в 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-проверок, расчёт деградаций.

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

API	Базовый URL	Авторизация
Seller API	api-seller.ozon.ru	заголовки `Client-Id` и `Api-Key`
Performance API (реклама)	api-performance.ozon.ru	OAuth `client_credentials`, токен на 30 минут

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

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

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

Переменная	По умолчанию	Зачем
`MCP_AUTH_TOKEN`	пусто	Bearer-токен для `/sse`. Пусто = без авторизации
`HEALTH_CHECK_INTERVAL_MIN`	`30`	интервал фоновой диагностики, `0` — выключить
`PORT`	`8000`	порт HTTP-сервера
`DATA_DIR`	`/data`	каталог с `shops.json`, `stats.db`, `.encryption_key`
`OZON_CLIENT_ID`, `OZON_API_KEY`	пусто	ключи Seller API для магазина `default`, если не хочется вводить их в UI
`OZON_PERF_CLIENT_ID`, `OZON_PERF_CLIENT_SECRET`	пусто	то же для Performance API

Известные ограничения 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 и те же способы подключения к клиентам.

	Ozon MCP Server	WB MCP Server
Порт	8000	8001
Инструментов	151	202
API	Ozon Seller API + Performance API (реклама)	Wildberries Seller API

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

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

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

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

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

Если исправление нужно срочно — напишите на d0371153@gmail.com. Issues и pull request'ы тоже приветствуются и разбираются.

Лицензия

MIT — см. LICENSE.

Ozon MCP Server

Documentation

Ozon MCP Server

Что умеет

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

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

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

Без Docker

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

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

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

Дашборд /

Магазины /shops

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

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

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

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

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

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

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

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

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

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

Лицензия

Дашборд `/`

Магазины `/shops`

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