Skip to main content
Glama

OZON MCP

Servidor MCP de código abierto para vendedores de Ozon, con una base de conocimientos operativos en chino de 42 lecciones y 466 métodos de API integrados, que permite a los agentes de IA buscar experiencias operativas, invocar las API de Seller/Performance y ejecutar operaciones comerciales reales.

Python License MCP Docker CI


Índice



Introducción del proyecto

OZON MCP es un servidor MCP basado en conocimiento, construido sobre el Model Context Protocol. Encapsula la documentación completa de las API de Ozon Seller y Performance, los esquemas de parámetros, las reglas de limitación de velocidad y los flujos de trabajo empresariales como herramientas MCP estandarizadas, lo que permite a agentes de IA como Claude, Cursor y Codex buscar, comprender e invocar directamente las API de Ozon.

Qué problema resuelve

La plataforma abierta de Ozon tiene dos conjuntos de API (Seller + Performance), con más de 460 endpoints distribuidos en 55 módulos empresariales. Consultar la documentación manualmente, construir solicitudes y gestionar la paginación y la limitación de velocidad consume mucho tiempo.

OZON MCP convierte a los agentes de IA en tu asistente de operaciones de Ozon:

  • El agente puede buscar métodos de API en chino o ruso para encontrar el endpoint necesario

  • Cada método devuelve un JSON Schema completamente analizado, incluidos parámetros de solicitud, estructura de respuesta, reglas de limitación y trampas conocidas

  • Las operaciones de escritura cuentan con múltiples capas de salvaguardas de seguridad para evitar errores

  • Admite paginación automática para recorrer grandes volúmenes de datos

  • Incluye 13 flujos de trabajo empresariales seleccionados que cubren escenarios como análisis de agotamiento de stock, diagnóstico de precios y revisión de la tienda

Para quién es

  • Vendedores de Ozon que desean utilizar IA para el análisis de operaciones diarias

  • Desarrolladores de herramientas de comercio electrónico transfronterizo que necesitan integrar capacidades de Ozon en sus agentes

  • Desarrolladores interesados en el protocolo MCP que quieren conocer implementaciones prácticas


Capacidades principales

Descubrimiento y navegación de API

Herramienta

Función

ozon_list_sections

Enumera todos los módulos de API (Seller + Performance), incluido el número de métodos de cada módulo

ozon_search_methods

Búsqueda de texto completo (clasificación BM25), compatible con chino y ruso, filtrable por módulo/API/nivel de seguridad

ozon_describe_method

Obtiene la documentación completa de un método: JSON Schema, limitación de velocidad, problemas conocidos, ejemplos y métodos relacionados

ozon_get_section

Enumera todos los métodos de un módulo específico

Flujos de trabajo empresariales

13 flujos de trabajo seleccionados que cubren las siguientes categorías empresariales:

Categoría

Ejemplos de flujos de trabajo

Pedidos

Sincronización de pedidos, gestión de envíos

Inventario

Análisis de riesgo de agotamiento, diagnóstico de rotación de inventario

Precios

Análisis de índice de precios, comparación de precios de competidores

Análisis

Informes de ventas, resumen de datos financieros

Publicidad

Datos de campañas publicitarias, análisis de efectividad promocional

Productos

Consulta masiva de información de productos, recorrido del árbol de categorías

Cada flujo de trabajo incluye: secuencia de pasos de operación, guía de paginación/concurrencia, esquema de base de datos recomendado, trampas conocidas e instrucciones de interpretación de resultados.

Ejecución segura

Herramienta

Función

ozon_call_method

Ejecuta una única llamada a la API con tres capas de protección (nivel de seguridad / permisos de suscripción / validación de esquema)

ozon_fetch_all

Recorrido con paginación automática, compatible con 4 modos de paginación (offset / cursor / last_id / page_number)

Información de referencia

Herramienta

Función

ozon_get_rate_limits

Consulta las reglas de limitación de velocidad por método/módulo/global

ozon_get_error_catalog

Consulta los códigos de error de la API de Ozon y sus soluciones

ozon_get_examples

Obtiene ejemplos reales de solicitudes para un método

ozon_get_swagger_meta

Consulta la versión y la fecha de actualización de la documentación de API integrada

ozon_get_related_methods

Busca otros métodos relacionados con un método específico

Permisos de suscripción

Herramienta

Función

ozon_list_methods_for_subscription

Enumera los métodos disponibles solo con un nivel de suscripción específico

ozon_get_subscription_status

Consulta el nivel de suscripción de la cuenta actual

Nota: la versión actual es un servidor de conocimiento: incluso sin configurar credenciales de API, todas las herramientas de descubrimiento, búsqueda, referencia y flujos de trabajo funcionan correctamente. Solo se necesitan credenciales para ejecutar llamadas reales a la API.

Panorama completo de métodos de API

El proyecto incluye un catálogo completo en chino de 466 métodos de la API de Ozon (methods_catalog.md) que cubre todas las áreas del negocio de vendedores de Ozon:

Área de negocio

Contenido cubierto

Gestión de productos

Carga y actualización de productos, atributos de categoría, productos económicos, productos digitales, precios e inventario de productos

Pedidos y logística

Consulta y cancelación de pedidos, entrega FBO/FBS/rFBS, seguimiento de paquetes, gestión de devoluciones, zonas de entrega

Almacenes y suministro

Gestión de almacenes FBS, solicitudes de suministro FBO, entrega directa FBP/puntos de intercambio/recogida en domicilio

Finanzas e informes

Informes financieros (liquidación de ventas/gastos/reembolsos), informes analíticos (tráfico/búsqueda/conversión), calificación del vendedor

Marketing y precios

Estrategias de precios, campañas de la plataforma Ozon, campañas propias del vendedor, promociones y publicidad

Servicio al cliente

Chat con compradores, gestión de reseñas, gestión de preguntas y respuestas, notificaciones push

Cuenta y autenticación

Gestión de claves de API, certificación de marca, certificados de calidad, información del panel del vendedor

Una vez conectado, el agente puede buscar en chino (por ejemplo, «consultar lista de pedidos», «actualizar inventario en lote») y, combinado con las descripciones en chino tipo tarjeta del catálogo, localizar rápidamente la API correcta y ejecutar la llamada. Cada método indica el método HTTP, la ruta del endpoint, el nivel de seguridad y los requisitos de suscripción, por lo que el agente puede determinar directamente si se necesita confirmación para operaciones de escritura o permisos de suscripción de nivel superior.


Base de conocimientos operativos de Ozon en chino

El proyecto incluye una base de conocimientos operativos de Ozon en chino completa, organizada a partir de 42 lecciones de cursos de comercio electrónico de Ozon, con 610 fragmentos de conocimiento buscables. El agente puede buscar en lenguaje natural en chino para localizar rápidamente experiencias operativas, procedimientos y guías para evitar errores.

Resumen de la base de conocimientos

Elemento

Contenido

Número de lecciones

42 lecciones

Fragmentos de conocimiento

610 fragmentos

Idioma

Chino simplificado

Tipo de fuente

Experiencia operativa de cursos

Motor de búsqueda

BM25 local

Búsqueda en chino

Segmentación de bigramas/trigramas + protección de términos comerciales

Base de datos

No requiere

Embedding

No requiere

Servicios externos

No requiere

Temas cubiertos

La base de conocimientos cubre todo el recorrido del vendedor de Ozon, desde la apertura de la tienda hasta el servicio posventa:

  • Modelos de negocio de la plataforma (venta replicada, selección cuidadosa, venta masiva, dropshipping)

  • Los cuatro modelos de cumplimiento: FBS, FBO, FBP, rFBS

  • Registro de tienda y cálculo de envío internacional

  • Configuración de almacenes y logística

  • Métodos de selección de productos y creación de un pool de selección

  • Verificación de peso y dimensiones de productos

  • Explicación detallada de los módulos del panel del vendedor

  • Optimización de fichas de producto y creación de imágenes principales

  • Estrategias de precios y cálculo de márgenes de beneficio

  • Campañas promocionales y publicidad

  • Cumplimiento de pedidos y proceso de envío

  • Gestión de devoluciones y pedidos excepcionales

  • Riesgos operativos y prevención de suspensiones de tienda

Herramientas MCP de conocimiento operativo

Herramienta

Uso

Parámetros principales

ozon_search_operations_knowledge

Buscar en la base de conocimientos operativos

query (palabras clave en chino), limit, module, lesson_id

ozon_get_operations_knowledge

Leer fragmento de conocimiento completo

chunk_id (de los resultados de búsqueda)

ozon_list_operations_topics

Explorar el índice de cursos

query, module, limit, offset

Orden de invocación recomendado: buscar primero → seleccionar chunk_id → leer la evidencia completa → organizar la respuesta.

Flujo de invocación del agente

graph TD
    A[客户提问] --> B{运营知识问题?}
    B -->|是| C[ozon_search_operations_knowledge]
    B -->|API数据问题| F[ozon_search_methods]
    C --> D[选择1-3个chunk_id]
    D --> E[ozon_get_operations_knowledge]
    E --> G{需要当前数据?}
    F --> G
    G -->|是| H[ozon_call_method / ozon_fetch_all]
    G -->|否| I[组织回答]
    H --> I
    I --> J[标注来源与时效风险]

Ejemplos de invocación

"¿Un principiante debería empezar con venta replicada o selección cuidadosa?"

El agente primero invoca ozon_search_operations_knowledge({"query": "新手先做跟卖还是精铺"}), y tras obtener los fragmentos relevantes, invoca ozon_get_operations_knowledge para leer la evidencia completa y responder basándose en el contenido del curso sobre las ventajas, desventajas y condiciones de aplicación de ambos modelos.

"¿Qué es un agente de carga y cuál es el proceso completo de envío rFBS?"

El agente busca "货代 rFBS 发货流程", obtiene los fragmentos relevantes de la lección 01 y explica el concepto de agente de carga y el flujo completo de rFBS desde la creación del pedido hasta la firma de recepción.

"¿Cómo se debe hacer la diferenciación en la selección cuidadosa?"

El agente busca "精铺差异化", obtiene de la lección 02 la evidencia completa sobre estrategias de diferenciación en la selección cuidadosa, y responde incluyendo dimensiones como optimización de fichas de producto, diferenciación de imágenes principales y estrategias de precios.

"¿Cómo se deben configurar los almacenes y la logística de Ozon?"

El agente busca "仓库物流设置" y obtiene de la lección 06 los pasos detallados y las consideraciones para la configuración de almacenes.

"¿Cómo se debe verificar el peso antes de publicar un producto?"

El agente busca "上架前核实重量" y obtiene de la lección 07 los métodos de verificación de peso y las trampas comunes.

"¿Qué se debe comprobar primero si un producto no tiene visibilidad?"

El agente busca "商品没有曝光" y obtiene el enfoque de diagnóstico de los fragmentos relacionados con fichas de producto, precios y ranking de búsqueda.

Límites de las respuestas

Aviso importante:

  • El conocimiento de los cursos es un resumen de experiencia operativa y no equivale a las reglas oficiales actuales de Ozon

  • Las comisiones, tarifas, tiempos de entrega, productos prohibidos, sanciones, políticas de publicidad y devoluciones pueden cambiar en cualquier momento

  • Los fragmentos con verification_required=true deben recordar al cliente que verifique la documentación oficial actual

  • Cuando se traten datos reales de la tienda, pedidos, inventario, productos, finanzas o publicidad del cliente, es obligatorio invocar la API real de Ozon

  • No se debe inventar contenido que no esté cubierto por la base de conocimientos

Actualización de la base de conocimientos

Para actualizar el conocimiento operativo en el futuro, reemplace los siguientes archivos:

  • src/ozon_mcp/operations_knowledge/data/manifest.yaml

  • src/ozon_mcp/operations_knowledge/data/chunks.jsonl

  • src/ozon_mcp/operations_knowledge/data/topics.json

  • src/ozon_mcp/operations_knowledge/data/ozon_operations_knowledge.md

A continuación, ejecute la validación:

uv run python scripts/validate_operations_knowledge.py
uv run pytest

Casos de uso

Escenario 1: Consultar pedidos pendientes de envío

"Ayúdame a consultar todos los pedidos pendientes de envío"

El agente primero usa ozon_search_methods para buscar «order list» o «订单列表», encuentra OrderAPI_GetOrderList, luego usa ozon_describe_method para ver la estructura de parámetros y, finalmente, usa ozon_fetch_all para recuperar todos los pedidos con paginación.

Escenario 2: Verificación de riesgo de agotamiento

"Ejecuta el flujo de trabajo de análisis de riesgo de agotamiento y mira qué SKU podrían quedarse sin stock"

El agente ejecuta ozon_get_workflow({"name": "oos_risk_analysis"}), invoca AnalyticsAPI_StocksTurnover siguiendo los pasos y marca los SKU de riesgo según las reglas de interpretación integradas en el flujo de trabajo.

Escenario 3: Revisión de salud de la tienda

"Haz una revisión completa del estado de mi tienda"

El agente ejecuta ozon_get_workflow({"name": "cabinet_health_check"}), invoca en paralelo las tres API de calificación, información de la tienda y tiempo de entrega, y resume los indicadores y estados.

Escenario 4: Exportación masiva de información de productos

"Extrae la información básica de todos los productos en venta"

El agente usa ozon_fetch_all para invocar ProductAPI_GetProductList, recorre automáticamente la paginación last_id y devuelve la lista completa de productos.

Escenario 5: No sé cómo usar una API

"¿Ozon tiene una API para consultar el inventario del almacén? ¿Cómo se rellenan los parámetros?"

El agente usa ozon_search_methods({"query": "warehouse stock"}) para encontrar el método correspondiente, luego usa ozon_describe_method para obtener el esquema completo de parámetros y ejemplos de invocación, y te ayuda a construir los parámetros de la solicitud.


Arquitectura del sistema

graph TD
    A[MCP 客户端<br/>Claude / Cursor / Codex / Windsurf] 
    B[OZON MCP Server<br/>FastMCP stdio]
    C[API 知识层<br/>Swagger + YAML]
    K[运营知识层<br/>BM25 + 中文分词]
    D[Seller API Client<br/>api-seller.ozon.ru]
    E[Performance API Client<br/>api-performance.ozon.ru]
    F[Ozon Seller API]
    G[Ozon Performance API]

    A -->|JSON-RPC over stdio| B
    B --> C
    B --> K
    B --> D
    B --> E
    D -->|Client-Id + Api-Key| F
    E -->|OAuth2 Bearer| G
    
    subgraph 安全守卫
        H[安全等级检查<br/>read/write/destructive]
        I[订阅权限校验]
        J[Schema 验证]
    end
    
    B --> H --> I --> J

Descripción de los módulos principales:

  • Capa de conocimiento: carga las definiciones completas de los 466 métodos desde los archivos Swagger integrados y la base de conocimientos YAML al iniciarse

  • Índice de búsqueda: motor de búsqueda de texto completo basado en BM25, compatible con segmentación en chino y ruso y ponderación de campos

  • Grafo de métodos: red de relaciones entre métodos construida automáticamente a partir de enlaces de documentación y flujos de trabajo

  • Gestión de limitación de velocidad: límites de velocidad por API, con cola automática y reintentos con retroceso

  • Salvaguardas de seguridad: validación en tres capas: nivel de seguridad (solo lectura/escritura/destructivo) → permisos de suscripción → validación de JSON Schema


Estructura del proyecto

ozon-mcp/
├── src/ozon_mcp/               # 核心代码
│   ├── __init__.py              # 版本号
│   ├── __main__.py              # CLI 入口,MCP stdio 启动
│   ├── config.py                # 环境变量配置(SecretStr 保护凭据)
│   ├── server.py                # FastMCP 服务器工厂
│   ├── state.py                 # 进程内缓存(订阅等级 TTL)
│   ├── errors.py                # 统一错误模型
│   ├── data/                    # Swagger API 文档
│   │   ├── seller_swagger.json  #   Seller API (420 方法)
│   │   ├── perf_swagger.json    #   Performance API (46 方法)
│   │   └── swagger_meta.json    #   文档版本元数据
│   ├── knowledge/               # 精选知识库(YAML)
│   │   └── ...                   #   工作流、限流、错误码等
│   ├── operations_knowledge/     # 中文运营知识库
│   │   ├── models.py             #   数据模型(Pydantic)
│   │   ├── loader.py             #   加载与完整性校验
│   │   ├── tokenizer.py          #   中文分词器
│   │   ├── search.py             #   BM25 检索引擎
│   │   └── data/                 #   知识库数据
│   │       ├── manifest.yaml     #     元数据
│   │       ├── chunks.jsonl      #     610 个知识片段
│   │       ├── topics.json       #     42 个课程主题
│   │       └── ozon_operations_knowledge.md  # 原始知识文档
│   ├── schema/                  # Schema 引擎
│   │   ├── extractor.py         #   OpenAPI → JSON Schema 提取
│   │   ├── search.py            #   BM25 全文搜索
│   │   ├── graph.py             #   方法关系图 (networkx)
│   │   ├── catalog.py           #   方法目录
│   │   └── resolver.py          #   $ref 内联解析
│   ├── tools/                   # MCP 工具定义(15 个)
│   │   ├── discovery.py         #   发现类工具 (4)
│   │   ├── execution.py         #   执行类工具 (2)
│   │   ├── reference.py         #   参考类工具 (4)
│   │   ├── workflow.py          #   工作流工具 (2)
│   │   ├── subscription.py      #   订阅工具 (2)
│   │   └── graph.py             #   图谱工具 (1)
│   └── transport/               # HTTP 传输层
│       ├── seller.py            #   Seller API 客户端
│       ├── performance.py       #   Performance API 客户端
│       ├── oauth.py             #   OAuth2 Token 管理
│       ├── ratelimit.py         #   速率限制
│       └── base.py              #   基类(重试、错误映射)
├── tests/                       # 测试
│   ├── unit/                    #   单元测试 (25 文件)
│   ├── integration/             #   集成测试 (4 文件)
│   ├── golden/                  #   回归测试 (3 文件)
│   └── live/                    #   真实 API 烟雾测试 (需凭据)
├── scripts/                     # 辅助脚本
│   ├── export_methods.py        #   导出方法目录
│   └── generate_subscription_overrides.py  # 生成订阅覆盖配置
├── Dockerfile                   # 多阶段 Docker 构建
├── pyproject.toml               # 项目配置
├── uv.lock                      # 依赖锁定
└── glama.json                   # Glama MCP 注册

Requisitos del entorno

Elemento

Requisito

Sistema operativo

Windows / macOS / Linux

Python

3.12 o 3.13

Gestor de paquetes

uv

Docker (opcional)

Para implementación en contenedores

Cuenta de Ozon

Solo se necesita para ejecutar llamadas a la API; la búsqueda de conocimiento no requiere credenciales

Permisos de la API de Ozon

  • Seller API: es necesario generar Client-Id y Api-Key en el panel de Ozon

  • Performance API: es necesario solicitar Client ID y Client Secret


Inicio rápido

Opción 1: Usar uv (recomendado)

# 克隆仓库
git clone https://github.com/yifan4243-sketch/OZON_MCP.git
cd OZON_MCP

# 安装依赖
uv sync

# 验证启动
uv run ozon-mcp --help

Si ve el mensaje de ayuda, la instalación se ha completado correctamente. En este punto puede conectarlo a un cliente MCP (consulte Configuración del cliente MCP).

Opción 2: Usar Docker

# 构建镜像
docker build -t ozon-mcp:local .

# 启动(stdio 模式,需要凭据)
docker run -i \
  -e OZON_CLIENT_ID=your_client_id \
  -e OZON_API_KEY=your_api_key \
  ozon-mcp:local

La imagen de Docker no incluye credenciales; deben pasarse mediante -e o --env-file.


Variables de entorno

Nombre de variable

¿Obligatoria?

Uso

Ejemplo

OZON_CLIENT_ID

Obligatorio al invocar la API de Seller

Seller API Client-Id

your_client_id

OZON_API_KEY

Obligatorio al invocar la API de Seller

Seller API Api-Key

your_api_key

OZON_PERFORMANCE_CLIENT_ID

Obligatorio al invocar la API de Performance

Performance OAuth Client ID

your_perf_client_id

OZON_PERFORMANCE_CLIENT_SECRET

Obligatorio al invocar la API de Performance

Performance OAuth Client Secret

your_perf_secret

OZON_LOG_LEVEL

No

Nivel de registro (por defecto INFO)

DEBUG

Todas las credenciales están protegidas con pydantic.SecretStr y no se imprimen ni registran accidentalmente en los registros.

Consulte .env.example para ver un ejemplo de configuración.


Configuración del cliente MCP

OZON MCP utiliza el protocolo MCP stdio. Las siguientes configuraciones se aplican a diferentes clientes MCP.

Claude Desktop

Edite el archivo de configuración:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ozon": {
      "command": "uv",
      "args": ["--directory", "D:/path/to/ozon-mcp", "run", "ozon-mcp"],
      "env": {
        "OZON_CLIENT_ID": "your_client_id",
        "OZON_API_KEY": "your_api_key"
      }
    }
  }
}

En Windows, use barras normales o dobles barras invertidas en las rutas, por ejemplo D:/ozon-mcp o D:\\ozon-mcp.

Claude Code (CLI)

# 在项目目录下执行
claude mcp add ozon -- uv run ozon-mcp

O edite manualmente ~/.claude/mcp.json:

{
  "mcpServers": {
    "ozon": {
      "command": "uv",
      "args": ["--directory", "/path/to/ozon-mcp", "run", "ozon-mcp"],
      "env": {
        "OZON_CLIENT_ID": "your_client_id",
        "OZON_API_KEY": "your_api_key"
      }
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "ozon": {
      "command": "uv",
      "args": ["--directory", "/path/to/ozon-mcp", "run", "ozon-mcp"],
      "env": {
        "OZON_CLIENT_ID": "your_client_id",
        "OZON_API_KEY": "your_api_key"
      }
    }
  }
}

Codex

Edite ~/.codex/mcp.json:

{
  "mcpServers": {
    "ozon": {
      "command": "uv",
      "args": ["--directory", "/path/to/ozon-mcp", "run", "ozon-mcp"],
      "env": {
        "OZON_CLIENT_ID": "your_client_id",
        "OZON_API_KEY": "your_api_key"
      }
    }
  }
}

Windsurf

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

{
  "mcpServers": {
    "ozon": {
      "command": "uv",
      "args": ["--directory", "/path/to/ozon-mcp", "run", "ozon-mcp"],
      "env": {
        "OZON_CLIENT_ID": "your_client_id",
        "OZON_API_KEY": "your_api_key"
      }
    }
  }
}

Otros clientes MCP

Cualquier cliente compatible con el protocolo MCP stdio puede conectarse. Configuración genérica:

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

Para más clientes, consulte la lista oficial de clientes MCP.


Ejemplos de invocación

Los siguientes ejemplos muestran la interacción en lenguaje natural con OZON MCP a través de un agente de IA.

Consultas

: Enumera los módulos de la API de Ozon Seller

El agente invoca ozon_list_sections y devuelve los 55 módulos con el número de métodos de cada uno.

: Busca todas las API relacionadas con «pedidos»

El agente invoca ozon_search_methods({"query": "订单"}) y devuelve los resultados coincidentes con sus puntuaciones.

: Consulta la documentación completa de OrderAPI_GetOrderList

El agente invoca ozon_describe_method({"operation_id": "OrderAPI_GetOrderList"}) y devuelve el JSON Schema completo, las reglas de limitación de velocidad y ejemplos de invocación.

Análisis

: Analiza la salud general de mi tienda

El agente ejecuta ozon_get_workflow({"name": "cabinet_health_check"}) para obtener los pasos del flujo de trabajo y luego invoca las API de calificación e información de la tienda siguiendo los pasos, y resume los resultados del análisis.

: ¿Qué productos tienen riesgo de agotamiento?

El agente ejecuta ozon_get_workflow({"name": "oos_risk_analysis"}), invoca la API de rotación de inventario y marca los SKU con estado DEFICIT y NO_SALES según las reglas de interpretación integradas en el flujo de trabajo.

Operaciones masivas

: Ayúdame a extraer todos los productos en venta

El agente invoca ozon_fetch_all({"operation_id": "ProductAPI_GetProductList", "params": {"filter": {"visibility": "ALL"}}}), recorre automáticamente la paginación y devuelve la lista completa de productos.

Solución de problemas

: La llamada a la API de lista de productos devolvió un error, código 429

El agente invoca ozon_get_error_catalog({"code": "429"}) para consultar la descripción y la solución del error de limitación de velocidad, y también usa ozon_get_rate_limits({"operation_id": "ProductAPI_GetProductList"}) para ver las reglas específicas de limitación de ese endpoint.


Desarrollo y pruebas

Instalar dependencias de desarrollo

uv sync --dev

Ejecutar pruebas

# 运行所有测试(跳过需要真实 API 凭据的测试)
uv run pytest -m "not live"

# 包含覆盖率报告
uv run pytest -m "not live" --cov=src/ozon_mcp --cov-report=term

Verificación de código

# Ruff 格式检查
uv run ruff check src/ tests/

# MyPy 类型检查
uv run mypy src/ozon_mcp/

Iniciar el servicio local

# 仅知识模式(无需凭据)
uv run ozon-mcp

# 带 Seller API 凭据
OZON_CLIENT_ID=xxx OZON_API_KEY=xxx uv run ozon-mcp

Compilación de Docker

docker build -t ozon-mcp:local .

Notas de seguridad

  • No envíe el archivo .env. Todas las credenciales se pasan mediante variables de entorno; .env ya está en .gitignore

  • No registre credenciales completas en los registros. Todos los campos de credenciales están protegidos con SecretStr; repr() y print() no revelan los valores reales

  • Use el principio de mínimo privilegio. Se recomienda crear claves de API de Ozon específicas para el servidor MCP, otorgando solo los permisos necesarios

  • Rote las claves periódicamente. Se recomienda actualizar las claves de API en el panel de Ozon con regularidad

  • Las operaciones de escritura requieren confirmación humana. Todas las operaciones write y destructive requieren un parámetro de confirmación adicional

  • Ejecute en un entorno de confianza. Se recomienda ejecutar localmente o en un servidor de confianza, sin exponerlo a Internet

  • Verifique las reglas de la plataforma antes de usar. Las reglas de limitación de velocidad, los requisitos de permisos y las políticas de tarifas de la API de Ozon pueden cambiar


Preguntas frecuentes

El cliente MCP no encuentra el servicio

Confirme que uv está instalado y en el PATH:

uv --version

El comando uv no existe

Instale uv:

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Las variables de entorno no surten efecto

Confirme que los nombres de las variables usan el prefijo OZON_ y que están configuradas correctamente. Puede probar con el siguiente comando:

OZON_LOG_LEVEL=DEBUG uv run ozon-mcp --help

La API de Ozon devuelve 401 o 403

Compruebe que OZON_CLIENT_ID y OZON_API_KEY son correctos y que las claves no han caducado.

Límite de frecuencia de solicitudes (429)

El servidor ya incluye reintentos automáticos y mecanismos de retroceso. Si sigue recibiendo 429, puede reducir la frecuencia de solicitudes concurrentes.

Error al iniciar Docker

Confirme que Docker está instalado y que el comando de compilación se ejecuta en el directorio raíz del proyecto:

docker build -t ozon-mcp:local .
docker run -i -e OZON_CLIENT_ID=xxx -e OZON_API_KEY=xxx ozon-mcp:local

Problemas de rutas en Windows

En la configuración del cliente MCP, use barras normales o dobles barras invertidas en las rutas:

"args": ["--directory", "D:/path/to/ozon-mcp", "run", "ozon-mcp"]

Cómo configurar varias tiendas

En la versión actual, un proceso de servidor MCP corresponde a una cuenta de Ozon. Para escenarios con varias tiendas, debe iniciar varias instancias del servidor, cada una con sus propias variables de entorno.

Conocimiento operativo no disponible (knowledge_unavailable)

Si la base de conocimiento operativo no se carga al inicio (por ejemplo, por archivos de datos dañados o faltantes), las tres herramientas de conocimiento operativo siguen existiendo, pero al invocarlas devuelven un error unificado:

{
  "error": "knowledge_unavailable",
  "error_type": "knowledge_unavailable",
  "message": "中文Ozon运营知识库当前不可用,请检查知识库资源是否完整并重新启动MCP Server。",
  "component": "operations_knowledge",
  "recovery_hint": "检查 src/ozon_mcp/operations_knowledge/data/ 下的 manifest.yaml、chunks.jsonl、topics.json 是否完整,然后重启 MCP Server。"
}

Descripción de los campos devueltos:

Campo

Valor

Descripción

error

"knowledge_unavailable"

Código de error legible por máquina

error_type

"knowledge_unavailable"

Valor de enumeración del tipo de error

message

Aviso en chino

Descripción legible para el agente

component

"operations_knowledge"

Componente con la avería

recovery_hint

Guía de recuperación

Acción de recuperación para el agente o el personal de operaciones

Nota: cuando la base de conocimiento no está disponible, la capa de conocimiento de la API y las demás herramientas siguen funcionando con normalidad; solo se ve afectada la función de recuperación de conocimiento operativo. Tras restaurar los archivos de la base de conocimiento y reiniciar, se recuperará automáticamente.


Licencia

Este proyecto es de código abierto bajo la Licencia MIT.


  • Este proyecto no es un proyecto oficial de Ozon ni tiene afiliación con Ozon.

  • Las interfaces, las reglas de limitación de tráfico, las políticas de comisiones y los requisitos de permisos de la API de Ozon pueden cambiar en cualquier momento.

  • El usuario debe cumplir por su cuenta con los términos de servicio de la plataforma Ozon y las leyes y normativas aplicables.

  • En operaciones de escritura y operaciones monetarias, se recomienda una revisión manual antes de ejecutarlas.

  • Este proyecto no se hace responsable de ninguna pérdida derivada del uso de este software.

-
license - not tested
-
quality - not tested
B
maintenance

Maintenance

Maintainers
Response time
Release cycle
Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

  • Hosted Amazon Seller Central and Amazon Ads MCP server for Claude, ChatGPT, Cursor, and agents.

  • Hosted Amazon Seller and Vendor MCP server for Claude, ChatGPT, Cursor, Codex, Gemini, Copilot.

  • First AI Agent e-commerce marketplace with 74+ AI products, MCP protocol, and Alipay payments

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/wbcyclist/OZON_MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server