Ozon MCP Server

Ozon MCP Server

Gestiona tus tiendas de Ozon directamente desde un chat con un asistente de IA: precios, promociones, publicidad, pedidos, devoluciones, reseñas, finanzas — 156 herramientas sobre la API de Vendedor de Ozon y la API de Rendimiento (Ozon es el marketplace más grande de Rusia; la API de Vendedor cubre catálogo y operaciones, la API de Rendimiento cubre anuncios pagados). Diseñado para vendedores que gestionan más de una tienda: cada llamada toma un shop_id, y las claves API permanecen cifradas en tu propio servidor — nada sale de él. Lo que lo diferencia de otros servidores MCP de Ozon: cubre publicidad además de la API de Vendedor, y su diagnóstico integrado te dice qué endpoints de Ozon fallaron antes de que tu asistente se tope con ellos.

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

Esta es la herramienta de trabajo del propio autor: más de cinco meses de uso diario, alrededor de veinte cuentas de vendedor, 156 herramientas. Se actualiza cuando él necesita que se actualice — consulta Actualizaciones y soporte para saber qué significa eso para ti.

Las guías de instalación por cliente en docs/ están actualmente solo en ruso. La configuración en ellas es JSON listo para pegar, que se lee igual en cualquier idioma: rutas de archivo, la URL http://localhost:8000/sse, y el encabezado Authorization: Bearer <MCP_AUTH_TOKEN>.

You: Which of my products is Ozon planning to pull into a promo?
You: Show ad campaign spend for the week and stop the ones burning money.
You: Which products have a worse price index than their competitors?
You: Reply with a thank-you to every new 5-star review.

Qué hace

Grupo	Herramientas	Qué incluye
Promociones y descuentos	14	Promociones de Ozon (lista, candidatos, unirse/salir), promociones propias del vendedor, solicitudes de compradores de "quiero un descuento"
Precios y estrategias de precios	14	fijar precios y el precio mínimo, índice de precios, temporizador de precio mínimo, estrategias automáticas que rastrean competidores
Publicidad (API de Rendimiento)	22	campañas CPC "Trafarety" (el formato de colocación patrocinada de Ozon), pujas y presupuestos, "Pago por pedido" (CPO), estadísticas por producto y diarias
Productos	21	listados y tarjetas, atributos, stock, importación y actualizaciones masivas, medios, archivo, certificados
Pedidos FBS y FBO	17	pedidos sin cumplir, empaquetado (v4), etiquetas, cancelaciones, actas de entrega, país de origen
Devoluciones y cancelaciones	10	lista unificada de devoluciones FBO+FBS, reclamaciones rFBS que requieren decisión del vendedor, solicitudes de cancelación
Reseñas, preguntas, chats	13	reseñas y respuestas, preguntas de compradores, conversaciones de chat (v3)
Almacenes e informes	8	almacenes FBS, métodos de entrega, generación y descarga de informes
Finanzas	7	saldo, transacciones, acumulaciones, informe de realización, liquidaciones mutuas, flujo de caja
Categorías, marcas, certificados	7	árbol de categorías, atributos y sus valores permitidos, certificados
Analítica	5	analítica de SKU, stock y rotación, posiciones de productos en la búsqueda de Ozon, consultas de búsqueda principales
Suministros FBO	4	órdenes 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 la API de Ozon, detector de degradación
Notificaciones	2	suscripciones a webhooks push y la referencia de tipos de eventos
Empresa	2	detalles del vendedor y tarifas
Tiendas	1	lista de tiendas conectadas y su shop_id

FBO y FBS son los modelos de cumplimiento de Ozon: FBO envía desde los almacenes de Ozon, FBS desde los tuyos, rFBS es FBS con tu propia entrega.

La lista numerada completa, con una descripción y los parámetros de cada herramienta, está en docs/tools.md. Se genera desde ozon_mcp/server.py (la constante TOOLS) — lo mismo que tools/list devuelve a cualquier cliente MCP.

Inicio rápido

Opción 1: un comando, sin Docker

El servidor habla stdio, que es como Claude Desktop, Cursor, VS Code y otros clientes MCP se conectan a él. Nada que compilar:

uvx ozon-mcp-server

O vía 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": "your Client-Id",
        "OZON_API_KEY": "your API key",
        "DATA_DIR": "~/.ozon-mcp"
      }
    }
  }
}

Apunta DATA_DIR a cualquier directorio escribible — contiene tiendas, claves y estadísticas. El valor predeterminado es /data, que es la ruta utilizada dentro de Docker.

Opción 2: Docker con el panel web

Usa esto si quieres el panel, el diagnóstico de la API de Ozon y la gestión de tiendas basada en navegador. Cinco comandos:

git clone https://github.com/DeviceIngineering/ozon-mcp-server.git
cd ozon-mcp-server
cp .env.example .env               # fine as-is for a trusted local network
docker compose up -d --build       # builds the image, serves on port 8000
open http://localhost:8000/shops   # add a store and its Ozon API keys

Qué hace cada paso:

• .env — cada variable es opcional. Las claves de tienda son más fáciles de ingresar en la interfaz web que aquí. Lo único que vale la pena configurar de antemano, si el servidor es accesible por alguien más que tú, es MCP_AUTH_TOKEN (genera una con openssl rand -hex 32).
• docker compose up -d --build — construye la imagen desde el Dockerfile, mapea el puerto 8000:8000 y crea el volumen ozon_data para tiendas, claves, estadísticas de llamadas e historial de diagnóstico. restart: unless-stopped trae el contenedor de vuelta después de un reinicio.
• /shops — el formulario de añadir tienda: shop_id (el identificador que usarás en el chat), un nombre para mostrar, Client-Id + Api-Key para la API de Vendedor, y Client-Id + Client-Secret para la API de Rendimiento. El botón "Проверить" (Probar) hace una solicitud en vivo a Ozon y te dice si las claves fueron aceptadas.

Una vez que está en ejecución:

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 la API de Ozon
http://localhost:8000/api/health	endpoint de salud, JSON
http://localhost:8000/sse	el endpoint MCP — esto es a lo que apuntan los clientes

Ten en cuenta que la interfaz web está en ruso.

Para 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, así que al ejecutarlo localmente asegúrate de apuntarlo a un directorio en el que puedas escribir.

Instalación en clientes

El transporte es SSE en http://<host>:8000/sse. El soporte de SSE difiere entre clientes: algunos lo hablan directamente, otros necesitan el puente mcp-remote. Hay una guía por cliente, con rutas de configuración para macOS, Linux y Windows y JSON listo — en ruso, pero los bloques JSON son neutrales en cuanto al idioma:

Cliente	SSE directamente	Guía
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, puente recomendado	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 corto, Claude Code:

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

Resumen del cliente y referencia del puente: docs/README.md.

Multi-tienda y seguridad

Las tiendas se añaden en la interfaz web, y cada herramienta toma un shop_id obligatorio; ozon_list_shops te dice cuáles existen. En el chat se ve así: "muéstrame el stock en la tienda alpha".

La ganancia real no es el cambio en sí, sino que una estrategia se escribe una vez y se despliega a cada cuenta: una regla sobre precios, respuestas a reseñas o pujas de anuncios se aplica a todas las tiendas a la vez — sin iniciar y cerrar sesión en cuentas de vendedor, sin copiar claves entre configuraciones de clientes.

El precio que pagas es una IP compartida. Cada cuenta habla con Ozon desde una dirección: el servidor en el que se ejecuta el MCP. Los límites de tasa de Ozon se cuentan por dirección, entre otras cosas, así que cuantas más cuentas tengas y más duro trabajen tus estrategias, más cerca estará el tráfico combinado del umbral donde se activa la limitación o un bloqueo.

• no hay límite en el número de tiendas en el código;
• el techo real proviene de los límites por IP de Ozon, no de este servidor;
• alrededor de veinte cuentas es la estimación del propio autor de dónde el tráfico aún permanece en la zona segura;
• más allá de eso, distribuye las tiendas entre varios servidores con diferentes direcciones.

Puedes ver cómo se acerca el límite, y el lugar para verlo es la interfaz web: los pings fallidos y las advertencias de diagnóstico comienzan a acumularse, y la proporción de errores en las estadísticas de llamadas salta. El panel también distingue los dos casos — la limitación masiva se ve como muchas herramientas degradándose a la vez, un endpoint roto como uno solo.

Cómo se almacenan las claves:

• en el primer uso, .encryption_key — una clave Fernet — se crea en DATA_DIR;
• las claves de tienda se cifran con ella y se guardan en DATA_DIR/shops.json;
• la interfaz web muestra las claves enmascaradas (abc***xyz), y guardar un valor enmascarado no sobrescribe el real;
• bajo Docker todo esto vive en el volumen ozon_data. Para moverte a otra máquina, copia todo el volumen — de lo contrario pierdes la clave de cifrado (consulta DEPLOY.md, en ruso).

Qué saber sobre el acceso:

• MCP_AUTH_TOKEN protege solo /sse. Pásalo como el encabezado Authorization: Bearer … o como un parámetro de consulta ?token=….
• Un MCP_AUTH_TOKEN vacío significa sin autenticación en absoluto. Solo aceptable en una red de confianza.
• La interfaz web (/, /shops, /diagnostics) y /api/* no están detrás del token: cualquiera que pueda alcanzar el puerto ve el panel y puede añadir tiendas.
• No expongas el puerto 8000 a internet directamente. Para acceso remoto usa Tailscale o una VPN.
• El servidor no termina HTTPS. Si necesitas TLS desde fuera, pon un proxy inverso delante.

La interfaz web: cada llamada es visible

Con un servidor MCP típico, las llamadas desaparecen en el vacío: el asistente hizo algo, pero qué exactamente, cuánto tardó y qué error encontró solo lo sabe el asistente. Aquí cada llamada obtiene una línea en el registro, y cada herramienta rota obtiene un marcador en el panel. Para una herramienta que mueve dinero real en una tienda, eso no es decoración — es la condición para confiar en ella.

Las estadísticas de llamadas y el historial de comprobaciones no son sintéticos: provienen de más de cinco meses de uso diario en aproximadamente veinte cuentas de vendedor. La lista de cambios detectados en la API de Ozon en la sección de limitaciones proviene del mismo lugar — se leyó del registro de degradación, no se copió de la documentación.

Panel /

La captura de pantalla está en la parte superior de esta página.

• Cuatro contadores en la parte superior: llamadas totales, llamadas de hoy, errores y duración promedio de llamada en milisegundos.
• Top 10 de herramientas: número de llamadas, duración promedio y cuántas de esas llamadas fallaron.
• Un feed de las últimas 50 llamadas: marca de tiempo, shop_id, nombre de la herramienta, duración, éxito o fallo, y el texto del error.
• Un filtro por tienda (/?shop=alpha) — las mismas cifras para una sola cuenta.
• Dos banners aparecen en la parte superior: herramientas degradadas y "la última comprobación de la API de Ozon encontró problemas".

Tiendas /shops

Las cuentas se añaden y eliminan directamente en el navegador, sin editar archivos y sin reiniciar el contenedor. El botón "Проверить" (Probar) hace una solicitud en vivo a ambas APIs (POST /api/shops/{shop_id}/test), así que las claves se verifican cuando las añades en lugar de durante la primera llamada real en medio de una tarea. Los tokens se cifran con Fernet, la clave de cifrado vive en DATA_DIR/.encryption_key, y la interfaz muestra las claves enmascaradas.

Diagnóstico /diagnostics

(la captura de pantalla muestra una tienda de demostración con claves deliberadamente inválidas, por eso cada sonda está en rojo)

• Por tienda: si las claves están configuradas, disponibilidad del host de Ozon, 12 sondas de categorías de Seller API y una verificación de clave de Performance API.
• Una verificación en segundo plano cada HEALTH_CHECK_INTERVAL_MIN minutos (30 por defecto, 0 la desactiva), más un botón "Проверить сейчас" (Verificar ahora) para una ejecución inmediata (POST /api/diagnostics/run).
• Historial de verificaciones: hora, tienda, estado, número de pings fallidos, número de sondas fallidas y los textos de advertencia. La interfaz muestra las últimas 30 entradas; hasta 1000 se conservan en la base de datos con rotación automática.
• Los mismos datos están disponibles desde el chat a través de la herramienta ozon_diagnostics.

Detector de degradación

El servidor nota por sí mismo que Ozon rompió o desactivó un endpoint — no por la documentación ni por trabajo fallido, sino por sus propias estadísticas. Una herramienta cuyas últimas tres llamadas consecutivas fallaron mientras que llamadas anteriores tuvieron éxito termina en la lista de degradación, que muestra el nombre de la herramienta, la hora de la última llamada exitosa, el número de errores consecutivos y el texto del más reciente. En el panel de control eso es un banner rojo; en la página de diagnóstico, una tabla.

Lo que esto te aporta: un cambio en el lado de Ozon se vuelve visible el día que ocurre, no una semana después cuando descubres que los precios no se han actualizado. La misma lista está disponible desde el chat mediante ozon_degradations.

JSON para monitoreo externo

Todo lo anterior se puede extraer programáticamente, no solo mirarse:

Endpoint	Qué devuelve
GET /api/health	estado del servicio, si la autenticación está activa, verificaciones recientes, herramientas degradadas
GET /api/stats	el mismo resumen que el panel de control; ?shop= lo limita a una tienda
GET /api/diagnostics/{shop_id}	una ejecución de diagnóstico completa en vivo para una tienda

Eso es suficiente para conectar el servidor a Zabbix, Uptime Kuma o un simple curl en cron.

Presupuesto de contexto

Dos cosas se pagan en tokens: definiciones de herramientas, cargadas una vez por sesión, y respuestas de herramientas, pagadas en cada llamada. Ambas se midieron en una cuenta de vendedor real en lugar de estimarse — scripts/collect_corpus.py toma una instantánea de las herramientas de solo lectura (PII enmascarada antes de escribir nada en disco, el corpus permanece fuera del repositorio), scripts/measure_corpus.py informa lo que cuesta.

Definiciones. 156 herramientas cuestan 12 300 tokens con una sola tienda configurada, frente a 18 386: descripciones de una oración, shop_id eliminado de los esquemas cuando solo existe una tienda, sin campos de esquema vacíos.

Respuestas. El problema real resultó ser un puñado de cargas útiles gigantes:

herramienta	antes	después
ozon_category_tree — un árbol de 9 797 nodos	266 324	979
ozon_get_prices — 93 % del peso es historial de promociones	52 879	8 679
ozon_returns_fbo — 50 devoluciones con logística completa	24 277	8 458
ozon_warehouse_list — 99 % del peso es un año de horarios	20 132	370
corpus de 16 respuestas en vivo	476 158	63 845

Lo que el servidor hace al respecto:

• view: compact | full. Las herramientas pesadas devuelven los campos para los que se les llama; view="full" da la respuesta cruda de la API, y la respuesta indica qué campos se ocultaron para que el modelo sepa qué puede pedir.
• Señal de truncamiento. Cuando vuelven exactamente limit registros, la respuesta dice que los datos son parciales — de lo contrario el modelo razona sobre un fragmento y lo presenta como el catálogo completo.
• Guardia de tamaño. Una respuesta que no quepa en el límite de salida del cliente (MAX_MCP_OUTPUT_TOKENS, 25 000 por defecto en Claude Code) se corta en el servidor con un recuento de lo que se omitió, en lugar de truncarse silenciosamente al llegar.
• Búsqueda y profundidad para el árbol de categorías. La API no tiene ninguna y devuelve los 9 797 nodos; search encuentra una categoría, depth controla el nivel, y el predeterminado es solo el nivel superior.

Las notas llegan como bloques de contenido separados en lugar de un campo dentro del JSON: varios endpoints de Ozon devuelven un arreglo en el nivel superior, y envolverlo rompería cada ruta hacia los datos.

Perfiles de herramientas. Un cliente sin búsqueda de herramientas paga por el catálogo completo en cada solicitud. OZON_TOOLSETS conserva solo los perfiles que usas, recortados según tareas de trabajo en lugar de secciones de documentación:

OZON_TOOLSETS	herramientas	tokens
vacío (predeterminado)	151	12 686
pricing,ads	57	5 425
orders	33	2 611

El perfil core — tiendas, diagnósticos, degradaciones, empresa — siempre está activo: los diagnósticos se necesitan exactamente cuando algo está roto. Los perfiles deshabilitados se enumeran en la descripción de ozon_list_shops, y llamar a una herramienta deshabilitada responde qué perfil la contiene, para que el asistente nombre la razón en lugar de decir "esto no es posible".

Claude Code no necesita nada de esto: tiene búsqueda de herramientas habilitada por defecto. Cursor, Cline, Continue y Claude Desktop obtienen tools/list completo — los perfiles son para ellos.

Decisiones de diseño

• 151 herramientas específicas, no unas pocas genéricas. Colapsarlas en endpoints estilo action ahorraría tokens de definición y cambiaría la clase de fallo: en lugar de "no existe tal herramienta" obtienes una llamada incorrecta con efecto secundario, y algunas de estas herramientas fijan precios e inician campañas publicitarias.
• El servidor se diagnostica a sí mismo. ozon_diagnostics verifica la disponibilidad del host y ejecuta una solicitud real ligera en 12 categorías de Seller API más las claves de Performance API; ozon_degradations informa qué herramientas solían funcionar y ahora fallan de manera constante. Ozon retira endpoints sin aviso, así que "¿son mis claves o se movió la API?" tiene que poder responderse en una sola llamada.
• compact es el predeterminado para herramientas pesadas. El corpus mostró que los campos ocultos son historial de promociones, horarios de almacén e internos de logística — no los datos con los que se toman decisiones — y la respuesta dice qué se ocultó.
• La configuración de respuestas cuelga de una contextvar. El despachador aquí es una larga cadena if con 150 llamadas a _json; pasar el nombre de la herramienta y los argumentos por cada rama a mano serían 150 sitios de edición y 150 oportunidades de fallar uno.
• shop_id desaparece de los esquemas con una tienda, y vuelve en el momento en que aparece una segunda.
• mcp<2 está fijado deliberadamente — la API de bajo nivel 2.0 elimina los manejadores de decorador sobre los que está construido este servidor; la fijación está documentada donde se establece.
• Las claves están cifradas en reposo (Fernet, clave en el volumen de datos) y enmascaradas en la interfaz; el recolector de corpus enmascara datos personales antes de escribir un archivo.

Cómo funciona

Un solo contenedor Docker que ejecuta una aplicación FastAPI que es tanto el servidor MCP como la interfaz web.

• ozon_mcp/server.py — el propio servidor MCP. La lista TOOLS describe las 156 herramientas (nombre, descripción, esquema JSON para los argumentos) y el manejador call_tool enruta cada llamada al método correcto del cliente de Ozon. Los clientes se agrupan por shop_id, así que cambiar de tienda no reconecta nada.
• ozon_mcp/client.py — dos clientes HTTP: OzonSellerClient (encabezados Client-Id / Api-Key) y OzonPerformanceClient (un token client_credentials que vive 30 minutos y se renueva solo).
• ozon_mcp/app.py — FastAPI: el endpoint /sse sobre SseServerTransport, verificación de token Bearer, las páginas de panel/tiendas/diagnóstico y la tarea de verificación de salud en segundo plano.
• ozon_mcp/settings.py — tiendas y claves: cifrado Fernet, enmascaramiento para la interfaz, recogida de claves de variables de entorno como una tienda llamada default y migración del antiguo settings.json de una sola tienda a shops.json.
• ozon_mcp/diagnostics.py — sondas: ping a hosts de Ozon más solicitudes reales ligeras en 12 categorías de Seller API y una verificación de clave de Performance API.
• ozon_mcp/stats.py — SQLite mediante aiosqlite: cada llamada de herramienta con su duración y resultado, historial de verificación de salud, cálculo de degradación.

Los hosts con los que habla el servidor:

API	URL base	Autorización
Seller API	api-seller.ozon.ru	encabezados Client-Id y Api-Key
Performance API (anuncios)	api-performance.ozon.ru	OAuth client_credentials, token de 30 minutos

Cosas no obvias:

• Ozon devuelve ofertas y presupuestos de anuncios en microrublos: 1000000 = 1 ₽. No te sorprendas por números de siete dígitos.
• Un 403 en reseñas y preguntas no es una avería — significa que no hay suscripción Premium Plus. El diagnóstico no cuenta esos como errores.
• Las claves de API de Ozon se volvieron limitadas en el tiempo después de la rotación del 2026-02-13 — 180 días. La expiración se expone explícitamente: POST /v1/roles devuelve expires_at, para que puedas advertir con antelación en lugar de atrapar un 401 en las sondas.
• Estadísticas de anuncios asíncronas: un informe a la vez, ≤10 campañas, ≤62 días. La herramienta espera hasta unos 2 minutos a que el informe esté listo.
• Los estados de pedidos de suministro en la API v3 son enteros 1–8, no cadenas.

Variables de entorno

Variable	Predeterminado	Propósito
MCP_AUTH_TOKEN	vacío	Token Bearer para /sse. Vacío = sin autenticación
HEALTH_CHECK_INTERVAL_MIN	30	intervalo de diagnóstico en segundo plano, 0 lo desactiva
PORT	8000	puerto del servidor HTTP
OZON_TOOLSETS	vacío	perfiles de herramientas separados por comas: pricing, ads, catalog, orders, analytics, feedback, finance; vacío significa las 156
OZON_MAX_RESPONSE_CHARS	60000	umbral de guardia de tamaño para una sola respuesta
DATA_DIR	/data	directorio que contiene shops.json, stats.db, .encryption_key
OZON_CLIENT_ID, OZON_API_KEY	vacío	claves de Seller API para la tienda default, si prefieres no usar la interfaz
OZON_PERF_CLIENT_ID, OZON_PERF_CLIENT_SECRET	vacío	lo mismo para la Performance API

Limitaciones conocidas de la API de Ozon (a agosto de 2026)

• Publicidad: la API solo puede crear campañas CPC "Trafarety"; presupuestos y ofertas están en microrublos; no hay forma oficial de leer el saldo de la cuenta publicitaria.

• "Pago por pedido": las ofertas están fijas desde febrero de 2025 — solo puedes activar o desactivar la promoción.

• Reseñas, preguntas y parte de la analítica requieren una suscripción Premium Plus (código de error 7).

• Las métricas de embudo en ozon_analytics están marcadas como obsoletas por Ozon — usa ozon_product_queries para posiciones de búsqueda.

• Endpoints que Ozon está apagando en otoño de 2026. Fechas del canal oficial @OzonSellerAPI, verificadas contra cuentas de vendedor reales (issue #6, gracias a @standlord-prog):

  ruta	se apaga	reemplazo
  /v3/posting/fbs/list	2026-08-31	/v4/posting/fbs/list — hecho en v2.1.0
  /v2/posting/fbo/list	2026-08-31	/v3/posting/fbo/list — hecho en v2.1.0
  /v3/posting/fbs/unfulfilled/list	2026-08-31	sin reemplazo: filtrado de /v4/posting/fbs/list por estado — hecho en v2.1.0
  /v2/posting/fbs/act/create	2026-09-07	/v1/carriage/create + /v1/carriage/approve — en progreso
  /v3/finance/transaction/list	2026-09-08	/v1/finance/accrual/by-day — en progreso
  /v3/finance/transaction/totals	2026-09-08	mismo — en progreso

  /v4/posting/fbs/list no es un renombrado de v3: postings están en el nivel superior en lugar de bajo result, y la paginación es basada en cursor (has_next + cursor) en lugar de offset.

• ozon_finance_cash_flow y ozon_finance_accruals ya funcionan en las nuevas rutas (/v1/finance/cash-flow-statement/list, /v1/finance/accrual/by-day).

• ozon_product_stocks_by_warehouse usa v2 porque v1 se apaga el 2026-04-07.

• Los actas de entrega digital de FBS fueron eliminados por Ozon el 2026-03-22 — se usa el acta regular en su lugar.

• La API de Ozon no tiene un método "editar respuesta a reseña": la respuesta se elimina y se escribe de nuevo. Esta lista no es una reescritura de la referencia: proviene del registro de degradaciones y de cinco meses de llamadas diarias, contrastada con docs.ozon.ru a agosto de 2026.

Qué cambió en la versión 2.0

Una revisión completa contra la API de Ozon de junio de 2026, verificada ejecutando solicitudes reales en lugar de leer la documentación: la lista unificada de devoluciones, cancelaciones v2, realización v2, envío v4, pedido de suministro v3, estrategias de precios reales y "Quiero un descuento", las promociones propias del vendedor, el nuevo modelo publicitario (Trafarety CPC + "Pago por pedido"), diagnósticos con detector de degradaciones y autenticación en el endpoint MCP.

Estructura del proyecto

ozon-mcp-server/
├── docker-compose.yml   # port 8000, ozon_data volume
├── Dockerfile           # python:3.12-slim, uvicorn
├── DEPLOY.md            # deploying to a dedicated machine, moving data
├── docs/                # client connection guides + tool reference
└── ozon_mcp/
    ├── server.py        # MCP server: 156 tools, multi-store
    ├── client.py        # Seller API + Performance API
    ├── app.py           # FastAPI: SSE, web, auth, health loop
    ├── diagnostics.py   # category probes, degradation detector
    ├── settings.py      # stores and keys (Fernet)
    ├── stats.py         # call statistics and check history (SQLite)
    └── templates/       # dashboard, diagnostics, shops

Despliegue en una máquina dedicada y traslado de tiendas: DEPLOY.md (en ruso).

El mismo servidor para Wildberries

wb-mcp-server es la misma herramienta para el otro marketplace (Wildberries es el otro gran marketplace ruso): misma arquitectura, misma interfaz web con panel y diagnósticos, mismo modelo multi-tienda vía shop_id, mismo transporte SSE, mismas formas de conectar clientes.

	Ozon MCP Server	WB MCP Server
Puerto	8000	8001
Herramientas	151	202
API	Ozon Seller API + Performance API (anuncios)	Wildberries Seller API

En la práctica, esto significa dos cosas:

• El segundo servidor no requiere nuevo aprendizaje. Una vez que has configurado uno, el otro arranca de la misma manera; solo difieren el puerto (8001 en lugar de 8000) y el conjunto de herramientas.
• Puedes ejecutar ambos en una sola máquina. Puertos diferentes, datos en volúmenes Docker separados, sin conflictos. En tu cliente son simplemente dos servidores MCP: ozon en http://localhost:8000/sse y wb en http://localhost:8001/sse.

Compartir una máquina tampoco afecta los límites de tasa: ambos salen desde la misma IP, pero Ozon y Wildberries cuentan los límites por su cuenta — son marketplaces diferentes. El tope en el número de cuentas de vendedor descrito en la sección de multi-tienda se aplica por separado dentro de cada marketplace.

Del acceso a la API a un repricer funcional

Este servidor da a un modelo acceso a la cuenta del vendedor. Decidir cuál debería ser el precio es una tarea aparte, y ozon-wildberries-repricer la realiza: mantiene un precio de referencia, calcula un umbral de punto de equilibrio a partir de las tarifas reales de cada marketplace, saca productos de promociones que los llevarían por debajo del costo, y puede buscar un mejor precio ejecutando un experimento controlado sobre ventas en vivo.

Cubre Ozon, Wildberries y Yandex Market en un solo lugar, y tiene su propio plano de control HTTP para agentes LLM — con las barreras que un modelo necesita: un movimiento de precio que dispararía la cuarentena de Wildberries se recorre en varias ejecuciones, los precios se releen tres minutos después porque los marketplaces reportan éxito para cambios que no hicieron, y varios agentes trabajando sobre el mismo catálogo no pueden sobrescribir las decisiones de los demás.

Ejecútalo sin una cuenta de marketplace: npm run demo genera un catálogo sintético e inicia la aplicación.

Actualizaciones y soporte

Ozon cambia su API constantemente: los endpoints se añaden, renombran y desactivan (la sección de limitaciones anterior enumera lo que se ha detectado hasta ahora). Este servidor es la herramienta de trabajo del autor, y se actualiza cuando él necesita que se actualice — es decir, cuando un cambio rompe algo en sus propias tiendas. Más de cinco meses de uso diario, y los commits aparecen cuando Ozon rompe algo, no según un calendario: una brecha entre commits normalmente significa que todo funciona. La ventaja es que el código está probado por el uso diario real en lugar de publicarse y olvidarse; la desventaja es que no hay calendario de lanzamientos ni compromiso de tiempos de respuesta.

Si necesitas una corrección urgente, escribe a d0371153@gmail.com. Los issues y pull requests también son bienvenidos, y sí se leen.

Agradecimientos

• @standlord-prog:
  • issue #6 — el desglose de los endpoints de Ozon que se desactivan, verificado contra cuentas de vendedor en vivo: fechas, reemplazos y tres trampas en la migración a /v4. Por separado — la advertencia de que /v1/carriage/create no tiene campos obligatorios y un cuerpo {} vacío crea un envío real, y la corrección sobre POST /v1/roles que devuelve expires_at. La versión v2.1.0 está construida sobre ese trabajo.
  • PR #7 — encontró y corrigió diagnósticos ciegos: en modo stdio las estadísticas de llamadas nunca se inicializaban, por lo que ozon_degradations respondía "sin degradaciones" a cada pregunta — incluso cuando cada llamada individual estaba fallando. La herramienta está marcada como [P0] y se consulta precisamente cuando algo se ha roto, lo que hace que un falso negativo silencioso sea peor que no tener herramienta alguna. El PR no solo corrige la conexión: también separa "sin datos" de "sin degradaciones" y añade una prueba de integración sobre stdio con un cliente MCP real. Incluido en v2.1.2.

Historial de versiones: CHANGELOG.md.

Licencia

MIT — ver LICENSE.

Registro MCP

Publicado en el Registro MCP oficial:

mcp-name: io.github.DeviceIngineering/ozon-mcp-server