ozon-mcp

Servidor MCP para las API de Ozon Seller & Performance. Conecta cualquier agente de IA a tu gabinete de Ozon en minutos.

ozon-mcp es un servidor MCP rico en conocimiento que convierte todo el kit de herramientas para vendedores de Ozon en 15 herramientas de alto impacto. Los agentes de IA (Claude, Cursor, Cline, Continue, Goose, Zed, …) pueden buscar en la API en ruso o inglés, profundizar en cualquiera de los 466 métodos con un esquema JSON totalmente resuelto y ejecutar llamadas con medidas de seguridad integradas. Con conocimiento de suscripción, paginación automática en los 4 estilos de cursor, reintento/retroceso en errores 429 y 13 flujos de trabajo analíticos listos para usar.

Datos clave: 466 métodos indexados (420 Seller + 46 Performance), 55 secciones, 5 niveles de suscripción modelados, 38 endpoints paginados recorridos automáticamente, 43 métodos destructivos con doble protección, 13 flujos de trabajo seleccionados para escenarios típicos de vendedor.

Inicio rápido

Requisitos previos

• Python 3.12 o 3.13

• Gestor de paquetes uv: instálalo con curl -LsSf https://astral.sh/uv/install.sh | sh

• Credenciales de la API de Ozon Seller (Client-Id + Api-Key): consíguelas en https://seller.ozon.ru/app/settings/api-keys

Instalación

git clone https://github.com/PCDCK/ozon-mcp.git
cd ozon-mcp
uv sync

Verifica que funciona

uv run ozon-mcp --help

Deberías ver la línea de uso de FastMCP. El servidor utiliza el protocolo stdio de MCP: apunta cualquier cliente compatible hacia él (instrucciones a continuación).

Related MCP server: Avito MCP

Conexión a tu agente de IA

ozon-mcp utiliza el transporte estándar stdio de MCP. Cada ejemplo a continuación expone las mismas 15 herramientas: elige el cliente que ya utilices.

Claude Desktop

Edita: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows).

{
  "mcpServers": {
    "ozon": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ozon-mcp",
                "run", "ozon-mcp"],
      "env": {
        "OZON_CLIENT_ID": "your-seller-client-id",
        "OZON_API_KEY": "your-seller-api-key",
        "OZON_PERFORMANCE_CLIENT_ID": "your-perf-client-id",
        "OZON_PERFORMANCE_CLIENT_SECRET": "your-perf-secret"
      }
    }
  }
}

Claude Code (CLI)

cd /path/to/ozon-mcp
claude mcp add ozon -- uv run ozon-mcp

O añádelo a ~/.claude/mcp.json con la misma estructura que la configuración de Claude Desktop anterior.

Cursor

Settings → MCP → Add new MCP Server, o edita ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ozon": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ozon-mcp",
                "run", "ozon-mcp"]
    }
  }
}

Windsurf

Edita ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "ozon": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ozon-mcp",
                "run", "ozon-mcp"]
    }
  }
}

Cline (extensión de VS Code)

Cline → Settings → MCP Servers → Add:

{
  "ozon": {
    "command": "uv",
    "args": ["--directory", "/absolute/path/to/ozon-mcp",
              "run", "ozon-mcp"]
  }
}

Continue.dev

Edita ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "uv",
          "args": ["--directory", "/absolute/path/to/ozon-mcp",
                    "run", "ozon-mcp"]
        }
      }
    ]
  }
}

Goose, Zed o cualquier otro cliente MCP

Cualquier cliente que utilice MCP stdio funcionará. Configuración genérica:

command: uv
args: ["--directory", "/absolute/path/to/ozon-mcp", "run", "ozon-mcp"]
transport: stdio
env:
  OZON_CLIENT_ID: ...
  OZON_API_KEY: ...

Explora la lista oficial de clientes MCP en https://modelcontextprotocol.io/clients.

Ejemplos de uso

Todos los ejemplos a continuación muestran respuestas realistas copiadas de tests/fixtures/responses/: identificadores anonimizados (99000001, TEST-SKU-001) pero con la estructura real.

Ejemplo 1: Obtener todos tus productos

Tú: Usa ozon_fetch_all con operation_id="ProductAPI_GetProductList" para obtener todos mis productos.

El agente llama a:

{
  "operation_id": "ProductAPI_GetProductList",
  "params": {"filter": {"visibility": "ALL"}},
  "max_items": 10000
}

El servidor recorre el cursor last_id automáticamente y devuelve:

{
  "ok": true,
  "items": [
    {"product_id": 99000001, "offer_id": "TEST-SKU-001", "archived": false},
    {"product_id": 99000002, "offer_id": "TEST-SKU-002", "archived": false},
    {"product_id": 99000003, "offer_id": "TEST-SKU-003", "archived": true}
  ],
  "total_fetched": 3,
  "truncated": false,
  "pages_fetched": 1
}

Ejemplo 2: Encontrar productos con riesgo de agotarse

Tú: Ejecuta el flujo de trabajo oos_risk_analysis para mi gabinete.

El agente primero inspecciona el flujo de trabajo:

ozon_get_workflow({"name": "oos_risk_analysis"})

→ le indica al agente que llame a AnalyticsAPI_StocksTurnover (limitado a 1 req/min: la cola por endpoint del servidor gestiona esto por ti) y cómo interpretar turnover_grade. La llamada devuelve:

{
  "items": [
    {"sku": 99000001, "current_stock": 12, "ads": 1.5,
     "idc": 8.0, "turnover_grade": "DEFICIT",
     "turnover_grade_cluster": "DEFICIT_GROWING"},
    {"sku": 99000002, "current_stock": 25, "ads": 0.8,
     "idc": 31.25, "turnover_grade": "OPTIMAL",
     "turnover_grade_cluster": "OPTIMAL_FALLING"},
    {"sku": 99000003, "current_stock": 0, "ads": 0.0,
     "idc": 0.0, "turnover_grade": "NO_SALES",
     "turnover_grade_cluster": "NO_SALES"}
  ]
}

El campo interpret del flujo de trabajo le indica al agente que marque los SKU donde idc < 14 o turnover_grade ∈ {DEFICIT, NO_SALES} y los muestre ordenados por idc asc.

Ejemplo 3: Verificación completa del estado del gabinete

Tú: Comprueba el estado de mi gabinete de Ozon usando el flujo de trabajo cabinet_health_check.

El flujo de trabajo le indica al agente que lea tres endpoints en paralelo: RatingAPI_RatingSummaryV1, SellerAPI_SellerInfo, AverageDeliveryTimeSummary. La primera llamada devuelve:

{
  "groups": [
    {
      "group_name": "Выполнение заказов",
      "items": [
        {"rating": "rating_on_time", "name": "Процент заказов вовремя",
         "current_value": 97.5, "status": "OK", "value_type": "PERCENT"},
        {"rating": "rating_review_avg_score", "name": "Средняя оценка",
         "current_value": 4.7, "status": "OK", "value_type": "RATING"}
      ]
    },
    {
      "group_name": "Качество сервиса",
      "items": [
        {"rating": "rating_price_index", "name": "Индекс цен",
         "current_value": 1.01, "status": "OK", "value_type": "INDEX"}
      ]
    }
  ],
  "premium_scores": [
    {"rating": "rating_on_time", "value": 97.5,
     "penalty_score_per_day": 0, "scope": "premium_plus"}
  ]
}

Ejemplo 4: Analizar el precio de los productos

Tú: ¿Cuáles de mis productos tienen un índice de precio rojo?

El agente ejecuta el flujo de trabajo pricing_analysis e inspecciona el campo price_indexes.color_index en cada artículo:

{
  "product_id": 99000001, "offer_id": "TEST-SKU-001",
  "price": {"price": "399.0000", "marketing_seller_price": "399.0000",
             "min_price": "299.0000"},
  "price_indexes": {
    "color_index": "WITHOUT_INDEX",
    "ozon_index_data": {"minimal_price": "395.0000",
                          "price_index_value": 1.01}
  },
  "commissions": {"sales_percent_fbo": 0.13, "sales_percent_fbs": 0.13}
}

La lista common_mistakes del flujo de trabajo le recuerda al agente que compare contra marketing_seller_price (el precio real que ve el comprador), no solo el price base.

Ejemplo 5: Auditoría de contenido

Tú: Encuentra productos con baja calificación de contenido y dime qué mejorar.

El agente ejecuta content_audit, obtiene las calificaciones por SKU + la lista de atributos que elevarían la puntuación:

{
  "products": [
    {
      "sku": 99000001, "rating": 85,
      "groups": [
        {"key": "media", "rating": 100},
        {"key": "characteristics", "rating": 75,
         "improve_attributes": [
           {"id": 4191, "name": "Цвет"},
           {"id": 8292, "name": "Материал"}
         ],
         "improve_at_least": 4}
      ]
    }
  ]
}

El flujo de trabajo le indica al agente que un aumento de +10 en rating mejora notablemente el ranking de búsqueda, por lo que completar esos dos atributos vale ≈ 4 puntos.

Herramientas disponibles (15)

Flujos de trabajo listos para usar (13)

Los flujos de trabajo son recetas paso a paso seleccionadas. Usa ozon_get_workflow("name") para obtener el plan completo, incluyendo interpret, when_to_use, common_mistakes y el esquema de base de datos recomendado para flujos de trabajo de tipo sincronización.

Cobertura de la API

Niveles de suscripción modelados (bajo → alto): LITE → STANDARD → PREMIUM → PREMIUM_PLUS → PREMIUM_PRO.

Características clave

Con conocimiento de suscripción

El servidor sabe qué métodos están restringidos a niveles Premium y rechaza la llamada antes de que salga de tu máquina, ahorrando tu cuota de API:

{
  "error": "subscription_gate",
  "error_type": "subscription_gate",
  "code": 7,
  "message": "Endpoint requires PREMIUM_PRO, cabinet has PREMIUM_PLUS",
  "operation_id": "ProductPricesDetails",
  "required_tier": "PREMIUM_PRO",
  "cabinet_tier": "PREMIUM_PLUS",
  "retryable": false,
  "http_call_skipped": true
}

Gestión de límites de tasa

• Reintento automático con retroceso exponencial en errores 429.

• Respeta Retry-After (tanto delta-segundos como fecha HTTP RFC 7231).

• Semáforo por endpoint para métodos lentos (ej. /v1/analytics/turnover/stocks está limitado a 1 req/min por parte de Ozon; el servidor pone en cola las llamadas paralelas automáticamente).

Paginación automática

ozon_fetch_all maneja los cuatro patrones de paginación que usa Ozon: offset/limit, cursor, last_id, page_number. También detecta el caso raro en el que el servidor devuelve el mismo cursor dos veces seguidas y rompe el bucle en lugar de girar para siempre.

ozon_fetch_all(
  operation_id="ProductAPI_GetProductList",
  params={"filter": {"visibility": "ALL"}},
  max_items=10_000,
)
# → {"items": [...all products...], "total_fetched": 847,
#    "truncated": false, "pages_fetched": 1}

Sobre de error unificado

Cada herramienta que puede fallar devuelve la misma estructura: fácil de ramificar en cualquier agente o código posterior:

{
  "error": "rate_limit_exceeded",
  "error_type": "rate_limit | subscription_gate | not_found | invalid_params | server_error | timeout | auth | forbidden | conflict | ...",
  "message": "Human-readable explanation",
  "code": 429,
  "operation_id": "AnalyticsAPI_StocksTurnover",
  "endpoint": "/v1/analytics/turnover/stocks",
  "retryable": true,
  "retry_after_seconds": 60
}

Clasificación de seguridad integrada en el catálogo

Cada método lleva un campo safety: read, write o destructive. write requiere confirm_write=True; destructive requiere tanto confirm_write=True COMO i_understand_this_modifies_data=True. Las heurísticas del extractor de esquemas se refuerzan con 43 entradas de safety_warning seleccionadas en quirks.yaml para que el agente siempre vea un recordatorio claro antes de modificar nada.

Mantener las especificaciones de la API actualizadas

Ozon actualiza su swagger periódicamente. Para sincronizar:

cd parser/                               # the parser repo / drop-zone
python parse_swagger.py                  # downloads + sanitises both APIs
cp seller_swagger.json ../src/ozon_mcp/data/
cp perf_swagger.json   ../src/ozon_mcp/data/
cp swagger_meta.json   ../src/ozon_mcp/data/

Ejecuta ozon_get_swagger_meta para confirmar que la instantánea incluida está fresca (la CI también falla la compilación cuando la instantánea tiene más de 14 días).

Desarrollo

git clone https://github.com/PCDCK/ozon-mcp.git
cd ozon-mcp
uv sync --extra dev

# Tests (≈25s, 274 currently)
uv run pytest tests/ --ignore=tests/live

# Code quality
uv run ruff check src tests
uv run mypy src/ozon_mcp

# Coverage
uv run pytest tests/ --ignore=tests/live --cov=src/ozon_mcp \
    --cov-report=term-missing

Consulta CONTRIBUTING.md para saber cómo añadir conocimiento (flujos de trabajo, ejemplos, peculiaridades, anulaciones de suscripción).

Licencia

MIT