Ozon MCP Server

Ozon Seller API + Performance API: 151 công cụ cho giá cả, khuyến mãi, quảng cáo, đơn hàng, trả hàng, tài chính và phân tích trên nhiều tài khoản người bán.

GitHub

Dùng thử MCP nàyĐược tài trợ

Tài liệu

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 стали срочными после ротации 13.02.2026 — 180 дней. Срок отдаётся явно: POST /v1/roles возвращает expires_at, так что об истечении можно предупреждать заранее, а не ловить его по 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.

Отключения Ozon осенью 2026. Даты из официального канала @OzonSellerAPI, сверены на живых кабинетах (issue #6, спасибо @standlord-prog):

путь	гаснет	что вместо
`/v3/posting/fbs/list`	31.08.2026	`/v4/posting/fbs/list` — сделано в v2.1.0
`/v2/posting/fbo/list`	31.08.2026	`/v3/posting/fbo/list` — сделано в v2.1.0
`/v3/posting/fbs/unfulfilled/list`	31.08.2026	замены нет: отбор из `/v4/posting/fbs/list` по статусам — сделано в v2.1.0
`/v2/posting/fbs/act/create`	07.09.2026	`/v1/carriage/create` + `/v1/carriage/approve` — в работе
`/v3/finance/transaction/list`	08.09.2026	`/v1/finance/accrual/by-day` — в работе
`/v3/finance/transaction/totals`	08.09.2026	то же — в работе

/v4/posting/fbs/list — не переименование v3: postings лежат на верхнем уровне, а не под result, и пагинация курсорная (has_next + cursor) вместо offset.

ozon_finance_cash_flow и ozon_finance_accruals уже работают на новых путях (/v1/finance/cash-flow-statement/list, /v1/finance/accrual/by-day).
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'ы тоже приветствуются и разбираются.

Благодарности

@standlord-prog:
- issue #6 — разбор отключаемых методов Ozon с проверкой на живых кабинетах: даты, замены и три подводных камня при переезде на /v4. Отдельно — предупреждение, что у /v1/carriage/create нет обязательных полей и пустое тело {} создаёт настоящую отгрузку, и поправка про POST /v1/roles с expires_at. На этой основе сделана версия v2.1.0.
- PR #7 — нашёл и починил слепую диагностику: в stdio-режиме статистика вызовов не поднималась вовсе, поэтому ozon_degradations на любой вопрос отвечал «деградаций нет» — даже когда падал каждый вызов. Инструмент помечен [P0] и нужен ровно в тот момент, когда что-то сломалось, так что тихий ложноотрицательный ответ был хуже отсутствия инструмента. В PR — не только починка, но и разделение «нет данных» и «нет деградаций», а также интеграционный тест по stdio настоящим MCP-клиентом. Вошло в v2.1.2.

Лицензия

MIT — см. LICENSE.

Ozon MCP Server

Tài liệu

Ozon MCP Server

Что умеет

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

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

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

Без Docker

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

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

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

Дашборд /

Магазины /shops

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

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

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

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

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

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

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

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

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

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

Благодарности

Лицензия

Дашборд `/`

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

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