Ozon MCP Server

Ozon MCP Server

Gestione tiendas de Ozon directamente desde el chat con un asistente de IA: precios, promociones, publicidad, pedidos, devoluciones, reseñas, finanzas: 151 herramienta sobre Ozon Seller API y Performance API. Para vendedores con varias tiendas: cada llamada acepta shop_id, las claves se almacenan cifradas en tu servidor, nada sale al exterior. Diferencia frente a otros Ozon-MCP: no solo cubre Seller API, sino también publicidad, y el diagnóstico integrado muestra qué métodos de Ozon fallaron, antes de que el asistente lo note.

¿También vendes en Wildberries? Existe el mismo servidor para WB: wb-mcp-server.

Esta es una herramienta de trabajo personal del autor: más de cinco meses de uso diario, alrededor de veinte cuentas, 151 herramienta. Se actualiza según las necesidades propias del autor: detalles en la sección «Actualizaciones y soporte».

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

Qué puede hacer

Grupo	Herramientas	Qué incluye
Promociones y descuentos	14	promociones de Ozon (lista, candidatos, entrada/salida), promociones propias del vendedor, solicitudes «Quiero descuento»
Precios y estrategias de precios	14	fijación de precios y precio mínimo, índice de precios, temporizador de precio mínimo, autoestrategias frente a competidores
Publicidad (Performance API)	22	campañas «Plantillas» (CPC), pujas y presupuestos, «Pago por pedido» (CPO), estadísticas por productos y días
Productos	21	lista y fichas, atributos, existencias, importación y actualización masiva, medios, archivo, certificados
Pedidos FBS y FBO	17	pedidos sin preparar, preparación (v4), etiquetas, cancelaciones, actas de recepción, país del producto
Devoluciones y cancelaciones	10	lista unificada de devoluciones FBO+FBS, solicitudes rFBS con decisión del vendedor, solicitudes de cancelación
Reseñas, preguntas, chats	13	reseñas y respuestas, preguntas de compradores, conversaciones en chats (v3)
Almacenes e informes	8	almacenes FBS, métodos de envío, generación y descarga de informes
Finanzas	7	saldo, transacciones, devengos, ventas, liquidaciones, movimiento de dinero
Categorías, marcas, certificados	7	árbol de categorías, atributos y sus valores, certificados
Analítica	5	analítica por SKU, existencias y rotación, posiciones de productos en búsqueda, top de consultas de búsqueda
Suministros FBO	4	solicitudes de suministro (v3), contadores, franjas horarias
Calificación	2	calificación actual del vendedor y su historial
Diagnóstico	2	autocomprobación de disponibilidad de Ozon API, detector de degradaciones
Notificaciones	2	suscripciones a webhooks push y directorio de tipos de eventos
Empresa	2	datos del vendedor y tarifas
Tiendas	1	lista de tiendas conectadas y su shop_id

Lista numerada completa con descripción de cada herramienta y sus parámetros: en docs/tools.md. Está generada a partir de ozon_mcp/server.py (constante TOOLS): lo mismo devuelve tools/list a cualquier cliente MCP.

Inicio rápido

Opción 1: un solo comando, sin Docker

El servidor funciona por stdio: así lo conectan Claude Desktop, Cursor, VS Code y otros clientes MCP. No hay que compilar nada:

uvx ozon-mcp-server

O mediante pip:

pip install ozon-mcp-server
ozon-mcp

Configuración del cliente (por ejemplo, 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 indique cualquier directorio con permiso de escritura: allí se guardan tiendas, claves y estadísticas. Por defecto se usa /data (ruta para Docker).

Opción 2: Docker con interfaz web

Necesaria si quiere un panel, diagnóstico de Ozon API y una forma cómoda de añadir tiendas a través del navegador. Cinco comandos:

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

Qué hace cada paso:

• .env: todas las variables son opcionales. Las claves de tiendas es más cómodo introducirlas en la interfaz web, no aquí. Lo único que conviene fijar de inmediato, si el servidor no lo ve solo usted, es MCP_AUTH_TOKEN (generar: openssl rand -hex 32).
• docker compose up -d --build: compila la imagen desde Dockerfile, expone el puerto 8000:8000 y crea el volumen ozon_data para tiendas, claves, estadísticas e historial de diagnóstico. restart: unless-stopped levantará el contenedor tras reiniciar la máquina.
• /shops: formulario para añadir tienda: shop_id (en latín, con él operará en el chat), nombre, Client-Id + Api-Key de Seller API y Client-Id + Client-Secret de Performance API. El botón «Comprobar» hace una solicitud real a Ozon y dice si las claves son válidas.

Tras el inicio:

Dirección	Qué es
http://localhost:8000/	panel: contadores de llamadas, errores, degradaciones
http://localhost:8000/shops	tiendas y claves
http://localhost:8000/diagnostics	diagnóstico de Ozon API
http://localhost:8000/api/health	endpoint de salud, JSON
http://localhost:8000/sse	endpoint MCP, es el que se indica a los clientes

Detener: docker compose down (los datos permanecen en el volumen ozon_data). Registros: docker compose logs -f.

Sin Docker

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

DATA_DIR por defecto es /data: en ejecución local, asegúrese de redefinirlo a un directorio accesible.

Instalación en clientes

Transporte: SSE, dirección http://<host>:8000/sse. El soporte SSE varía según el cliente: unos lo entienden directamente, otros necesitan el puente mcp-remote. Con un archivo de instrucciones para cada cliente, con rutas de configuración para macOS, Linux, Windows y JSON listo:

Cliente	SSE directo	Instrucciones
Claude Code	sí	docs/install-claude-code.md
Claude Desktop	no, puente mcp-remote	docs/install-claude-desktop.md
Cursor	sí	docs/install-cursor.md
Windsurf / Devin Desktop	sí	docs/install-windsurf.md
VS Code (GitHub Copilot)	sí	docs/install-vscode-copilot.md
Cline	sí	docs/install-cline.md
Continue.dev	sí	docs/install-continue.md
Zed	no confirmado, recomendamos puente	docs/install-zed.md
JetBrains AI Assistant / Junie	sí	docs/install-jetbrains.md
Gemini CLI	sí	docs/install-gemini-cli.md
OpenAI Codex CLI	no, puente mcp-remote	docs/install-codex.md

El ejemplo más breve: Claude Code:

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

Resumen de clientes y referencia del puente: docs/README.md.

Multi-tienda y seguridad

Las cuentas se añaden en la interfaz web; cada herramienta acepta el parámetro obligatorio shop_id; para conocer las disponibles, use la herramienta ozon_list_shops. En el chat se ve así: «muestra existencias en la tienda alpha».

La ventaja principal no es solo el cambio en sí, sino que la estrategia se escribe una vez y se despliega en todas las cuentas: una regla de precios, de respuestas a reseñas o de pujas se aplica a todas las tiendas a la vez, sin volver a iniciar sesión en cada cuenta ni copiar claves entre configuraciones de distintos clientes.

El precio de este enfoque es una IP compartida. Todas las cuentas acceden a Ozon desde una misma dirección: la del servidor donde está MCP. Los límites de Ozon se calculan también por dirección, y cuantas más cuentas y más activas sean las estrategias, más cerca estará el flujo total del umbral a partir del cual comienza el throttling o el bloqueo.

• no hay límite de número de tiendas en el código;
• el techo real no lo pone el servidor, sino los límites de Ozon por IP;
• alrededor de veinte cuentas es la estimación del autor para que el flujo se mantenga en zona segura;
• más allá, conviene repartir las tiendas entre varios servidores con direcciones distintas.

La cercanía al límite se ve con antelación, precisamente en la interfaz web: aumentan los pings fallidos y las advertencias en el diagnóstico, y en las estadísticas de llamadas sube la proporción de errores. Distinguir una cosa de otra también se puede por el panel: un throttling masivo se ve como una degradación simultánea de muchas herramientas; una avería de endpoint, como la degradación de una sola.

Cómo se guardan las claves:

• en el primer acceso a DATA_DIR se crea .encryption_key: una clave Fernet;
• las claves de tiendas se cifran con ella y quedan en DATA_DIR/shops.json;
• en la interfaz web las claves se muestran enmascaradas (abc***xyz); al guardar, el valor enmascarado no sobrescribe el real;
• en Docker todo esto está en el volumen ozon_data; migrar a otra máquina implica copiar el volumen completo; de lo contrario se pierde la clave de cifrado (ver DEPLOY.md).

Qué saber sobre el acceso:

• MCP_AUTH_TOKEN protege solo /sse. El token se envía en la cabecera Authorization: Bearer … o como parámetro ?token=….
• MCP_AUTH_TOKEN vacío = autorización desactivada. Solo así en una red de confianza.
• La interfaz web (/, /shops, /diagnostics) y /api/* no están protegidas por token: quien tenga acceso de red al puerto ve el panel y puede añadir tiendas.
• No exponga el puerto 8000 directamente a internet. Para acceso externo, use Tailscale o VPN.
• El servidor no termina HTTPS. Si necesita acceso externo por TLS, ponga un reverse proxy.

Interfaz web: cada llamada a la vista

En un servidor MCP normal, las llamadas se pierden: el asistente hizo algo, pero qué exactamente, en cuánto tiempo y con qué error solo lo sabe él. Aquí cada llamada tiene una línea en el registro, y cada herramienta que falla, una marca en el panel. Para una herramienta que gestiona dinero real en una tienda, esto no es un adorno, sino una condición de confianza.

Las estadísticas de llamadas y el historial de comprobaciones no son sintéticos: más de cinco meses de uso diario en unas veinte cuentas. De ahí sale también la lista de cambios detectados en Ozon API en la sección de limitaciones: no está copiada de la documentación, sino tomada del registro de degradaciones.

Panel /

Captura de pantalla: al principio de la página.

• Cuatro contadores arriba: total de llamadas, de hoy, errores, duración media de llamada en milisegundos.
• Top-10 de herramientas: cuántas veces se llamaron, tiempo medio, cuántas de ellas terminaron en error.
• Registro de las últimas 50 llamadas: hora, shop_id, nombre de la herramienta, duración, éxito o error y texto del error.
• Filtro por tienda (/?shop=alpha): las mismas cifras para una sola cuenta.
• Arriba aparecen dos avisos: sobre herramientas degradadas y sobre que la última comprobación de Ozon API encontró problemas.

Tiendas /shops

Las cuentas se añaden y eliminan directamente en el navegador, sin editar archivos ni reiniciar el contenedor. El botón «Comprobar» hace una solicitud real a ambas API (POST /api/shops/{shop_id}/test): las claves se verifican al añadirlas, no en la primera llamada de trabajo en medio de una tarea. Los tokens se cifran con Fernet; la clave de cifrado está en DATA_DIR/.encryption_key; en la interfaz las claves se muestran enmascaradas.

Diagnóstico /diagnostics

(en la captura: tienda de demostración con claves deliberadamente incorrectas, por eso todas las pruebas están en rojo)

• Por cada tienda: si las claves están definidas, disponibilidad de los hosts de Ozon, 12 pruebas de categorías de Seller API, comprobación de claves de Performance API.
• Comprobación en segundo plano cada HEALTH_CHECK_INTERVAL_MIN minutos (por defecto 30; 0 para desactivarla) y botón «Comprobar ahora» para una ejecución inmediata (POST /api/diagnostics/run).
• Historial de comprobaciones: hora, tienda, estado, número de pings fallidos, número de pruebas fallidas y texto de las advertencias. En la interfaz se muestran las últimas 30 entradas; en la base se guardan hasta 1000 con rotación automática.
• Los mismos datos están disponibles desde el chat con la herramienta ozon_diagnostics.

Detector de degradaciones

El servidor detecta por sí mismo que Ozon rompió o desactivó un endpoint: no por la documentación ni por el hecho de que una tarea fallara, sino por sus propias estadísticas. Una herramienta cuyas últimas tres llamadas consecutivas terminaron en error, pero antes tenían éxito, entra en la lista de degradaciones: allí se ve el nombre de la herramienta, la hora de la última llamada exitosa, el número de errores consecutivos y el texto del último. En el panel es una franja roja; en la página de diagnóstico, una tabla. Практический смысл: изменение на стороне 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.