OZON MCP

MCP-сервер с открытым исходным кодом для продавцов Ozon, включающий базу знаний по операционному управлению на китайском языке из 42 уроков и 466 методов API, позволяющий AI-агентам искать опыт ведения бизнеса, вызывать Seller/Performance API и выполнять реальные бизнес-операции.

Содержание

• О проекте

• Ключевые возможности

• Сценарии использования

• Системная архитектура

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

• Требования к окружению

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

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

• Настройка MCP-клиента

• Примеры вызовов

• Разработка и тестирование

• Замечания по безопасности

• Часто задаваемые вопросы

• Лицензия

• Отказ от ответственности

О проекте

OZON MCP — это сервер MCP, основанный на знаниях и построенный на Model Context Protocol. Он инкапсулирует полную документацию по API Ozon Seller API и Performance API, схемы параметров, правила ограничения частоты запросов и бизнес-процессы в стандартизированные MCP-инструменты, позволяя таким AI-агентам, как Claude, Cursor, Codex, напрямую искать, понимать и вызывать Ozon API.

Какую проблему решает

У открытой платформы Ozon есть два набора API (Seller + Performance), всего более 460 интерфейсов, распределённых по 55 бизнес-модулям. Ручной поиск по документации, сборка запросов, обработка пагинации и ограничений частоты запросов отнимают много времени.

OZON MCP превращает AI-агента в вашего ассистента по работе с Ozon:

• Агент может искать методы API на китайском или русском языке, чтобы найти нужный интерфейс

• Каждый метод возвращает полностью разобранную JSON-схему, включая параметры запроса, структуру ответа, правила ограничения частоты и известные ошибки

• При выполнении операций записи действует многоуровневая защита безопасности, предотвращающая случайные операции

• Поддерживается автоматическая пагинация для обхода больших объёмов данных

• Встроены 13 отобранных бизнес-процессов, охватывающих анализ риска дефицита, диагностику ценообразования, проверку магазина и другие сценарии

Кому подходит

• Продавцам Ozon, которые хотят использовать ИИ для повседневного операционного анализа

• Разработчикам инструментов для трансграничной электронной коммерции, которым необходимо интегрировать возможности Ozon в агента

• Разработчикам, интересующимся протоколом MCP и желающим узнать о реальных вариантах его внедрения

Ключевые возможности

Обнаружение API и навигация

Бизнес-процессы

13 отобранных процессов, охватывающих следующие бизнес-категории:

Каждый процесс включает: последовательность шагов, рекомендации по пагинации/параллелизму, рекомендуемую схему базы данных, известные ошибки и пояснения по интерпретации результатов.

Безопасное выполнение

Справочная информация

Права подписки

Примечание: текущая версия — это сервер знаний — все инструменты обнаружения, поиска, справки и рабочих процессов работают даже без настройки учётных данных API. Учётные данные требуются только для выполнения реальных вызовов API.

Обзор методов API

Проект включает полный каталог на китайском языке из 466 методов Ozon API (methods_catalog.md), охватывающий все сферы бизнеса продавцов Ozon:

После подключения агент может искать на китайском языке (например, «запросить список заказов», «массово обновить остатки»), используя карточки-каталоги с китайскими описаниями, чтобы быстро найти нужный API и выполнить вызов. Для каждого метода указаны HTTP-метод, путь интерфейса, уровень безопасности и требования к подписке, поэтому агент может сразу определить, требуется ли подтверждение на запись или права повышенной подписки.

База знаний по ведению бизнеса на Ozon на китайском языке

Проект включает полную базу знаний по ведению бизнеса на Ozon на китайском языке, составленную на основе 42 уроков по электронной коммерции Ozon и содержащую 610 доступных для поиска фрагментов знаний. Агент может искать на китайском языке с помощью естественного языка, быстро находя опыт ведения бизнеса, операционные процедуры и руководства по предотвращению ошибок.

Обзор базы знаний

Охватываемые темы

База знаний охватывает весь путь продавца Ozon — от открытия магазина до послепродажного обслуживания:

• Модели ведения бизнеса на платформе (торговля по чужой цене, точечная торговля, массовая торговля, дропшиппинг)

• Четыре модели исполнения: FBS, FBO, FBP, rFBS

• Регистрация магазина и расчёт международной стоимости доставки

• Настройка склада и логистики

• Методы выбора товара и создание пула товаров

• Проверка веса и габаритов товара

• Подробный обзор панели продавца

• Оптимизация карточки товара и создание главного изображения

• Стратегии ценообразования и расчёт рентабельности

• Продвижение и рекламные кампании

• Процесс выполнения заказа и отгрузки

• Обработка возвратов и нестандартных заказов

• Операционные риски и предотвращение блокировки магазина

MCP-инструменты базы знаний

Рекомендуемая последовательность вызовов: сначала поиск → выбор chunk_id → чтение полного доказательства → формирование ответа.

Процесс вызова агента

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[标注来源与时效风险]

Примеры вызовов

«Что новичку делать в первую очередь: торговать по чужой цене или точечно?»

Агент сначала вызывает ozon_search_operations_knowledge({"query": "新手先做跟卖还是精铺"}), получает релевантные фрагменты, затем вызывает ozon_get_operations_knowledge для чтения полного доказательства и на основе содержания курса объясняет преимущества, недостатки и условия применимости обеих моделей.

«Что такое логистический посредник, и каков полный процесс доставки rFBS?»

Агент ищет "货代 rFBS 发货流程", получает релевантные фрагменты из урока 01 и, опираясь на содержание курса, объясняет концепцию логистического посредника и полный путь rFBS от заказа до получения.

«Как провести дифференциацию при точечной торговле?»

Агент ищет "精铺差异化", получает из урока 02 полные доказательства стратегии дифференциации при выборе товаров для точечной торговли, а ответ включает оптимизацию карточки товара, дифференциацию главного изображения, стратегии ценообразования и другие аспекты.

«Как настроить склад и логистику Ozon?»

Агент ищет "仓库物流设置", получает из урока 06 подробные шаги по настройке склада и меры предосторожности.

«Как проверить вес товара перед размещением?»

Агент ищет "上架前核实重量", получает из урока 07 методы проверки веса и типичные ошибки.

«Что проверить в первую очередь, если у товара нет показов?»

Агент ищет "商品没有曝光", получает диагностические соображения по карточке товара, ценообразованию, позициям в поиске и другим связанным фрагментам.

Границы ответов

Важное примечание:

• Знания из курсов — это обобщение опыта ведения бизнеса и не являются действующими официальными правилами Ozon

• Комиссии, тарифы, сроки доставки, запрещённые товары, штрафы, реклама и политика возвратов могут меняться в любое время

• Для фрагментов с verification_required=true необходимо напомнить клиенту перепроверить актуальные официальные материалы

• При работе с реальными данными магазина, заказов, остатков, товаров, финансов или рекламы клиента обязательно вызывать реальный Ozon API

• Если в базе знаний нет информации по запросу, нельзя её выдумывать

Обновление базы знаний

При будущем обновлении операционных знаний замените следующие файлы:

• 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

Затем выполните проверку:

uv run python scripts/validate_operations_knowledge.py
uv run pytest

Сценарии использования

Сценарий 1: Запрос заказов, ожидающих отгрузки

«Найди все заказы, ожидающие отгрузки»

Агент сначала ищет ozon_search_methods по запросу "order list" или «список заказов», находит OrderAPI_GetOrderList, затем использует ozon_describe_method для просмотра структуры параметров и, наконец, с помощью ozon_fetch_all постранично выгружает все заказы.

Сценарий 2: Проверка риска дефицита

«Запусти анализ риска дефицита и посмотри, каким SKU может не хватить товара»

Агент запускает ozon_get_workflow({"name": "oos_risk_analysis"}), пошагово вызывает AnalyticsAPI_StocksTurnover и, следуя встроенным в процесс правилам интерпретации, помечает SKU из группы риска.

Сценарий 3: Проверка здоровья магазина

«Проверь состояние моего магазина»

Агент запускает ozon_get_workflow({"name": "cabinet_health_check"}), параллельно вызывает три интерфейса: рейтинг, информацию о магазине и сроки доставки, и обобщает показатели и статусы.

Сценарий 4: Массовый экспорт информации о товарах

«Выгрузи основную информацию обо всех товарах в продаже»

Агент использует ozon_fetch_all для вызова ProductAPI_GetProductList, автоматически обходит пагинацию last_id и возвращает полный список товаров.

Сценарий 5: Непонятно, как использовать какой-либо API

«Есть ли у Ozon интерфейс для запроса остатков на складе? Как заполнять параметры?»

Агент использует ozon_search_methods({"query": "warehouse stock"}) для поиска соответствующего метода, затем ozon_describe_method для получения полной схемы параметров и примера вызова, после чего помогает собрать параметры запроса.

Системная архитектура

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

Описание ключевых модулей:

• Уровень знаний: при запуске загружает полные определения 466 методов из встроенных Swagger-файлов и YAML-базы знаний

• Поисковый индекс: полнотекстовый поиск на основе BM25 с поддержкой китайской и русской сегментации и взвешивания полей

• Граф методов: автоматически построенная сеть взаимосвязей методов на основе ссылок в документации и рабочих процессов

• Управление ограничениями: ограничение частоты на уровне каждого API, автоматическая постановка в очередь и повторные попытки с экспоненциальной задержкой

• Защита безопасности: трёхуровневая проверка — уровень безопасности (только чтение/запись/деструктивные) → права подписки → проверка JSON Schema

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

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 注册

Требования к окружению

Права Ozon API

• Seller API: необходимо сгенерировать Client-Id и Api-Key в панели Ozon

• Performance API: необходимо запросить Client ID и Client Secret

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

Способ 1: с помощью uv (рекомендуется)

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

# 安装依赖
uv sync

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

Появление справочной информации означает успешную установку. Теперь можно подключаться к MCP-клиенту (см. Настройка MCP-клиента).

Способ 2: с помощью 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

Образ Docker не содержит учётных данных, их необходимо передавать через -e или --env-file.

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

Все учётные данные защищены с помощью pydantic.SecretStr и не будут случайно выведены в лог или записаны в журнал.

Пример конфигурации см. в .env.example.

Настройка MCP-клиента

OZON MCP использует протокол MCP stdio. Ниже приведены конфигурации для различных MCP-клиентов.

Claude Desktop

Отредактируйте файл конфигурации:

• 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"
      }
    }
  }
}

В Windows используйте прямые или двойные обратные слэши, например D:/ozon-mcp или D:\\ozon-mcp.

Claude Code (CLI)

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

Или вручную отредактируйте ~/.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, или отредактируйте ~/.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

Отредактируйте ~/.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

Отредактируйте ~/.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"
      }
    }
  }
}

Другие MCP-клиенты

Подойдёт любой клиент, поддерживающий протокол MCP stdio. Универсальная конфигурация:

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

Другие клиенты см. в официальном списке клиентов MCP.

Примеры вызовов

Ниже приведены примеры взаимодействия с OZON MCP через AI-агента на естественном языке.

Запросы

Вы: Перечисли модули Ozon Seller API

Агент вызывает ozon_list_sections, возвращает 55 модулей и количество методов в каждом.

Вы: Найди все интерфейсы, связанные с «заказами»

Агент вызывает ozon_search_methods({"query": "订单"}), возвращает совпадения и оценки.

Вы: Покажи полную документацию по OrderAPI_GetOrderList

Агент вызывает ozon_describe_method({"operation_id": "OrderAPI_GetOrderList"}), возвращает полную JSON Schema, правила ограничения частоты и пример вызова.

Анализ

Вы: Проанализируй общее состояние моего магазина

Агент запускает ozon_get_workflow({"name": "cabinet_health_check"}) для получения шагов процесса, затем пошагово вызывает интерфейсы рейтинга, информации о магазине и т.д., обобщая результаты анализа.

Вы: Какие товары находятся в зоне риска дефицита

Агент запускает ozon_get_workflow({"name": "oos_risk_analysis"}), вызывает интерфейс оборачиваемости запасов и, следуя встроенным в процесс правилам интерпретации, помечает SKU со статусами DEFICIT и NO_SALES.

Массовые операции

Вы: Выгрузи все товары в продаже

Агент вызывает ozon_fetch_all({"operation_id": "ProductAPI_GetProductList", "params": {"filter": {"visibility": "ALL"}}}), автоматически обходит пагинацию и возвращает полный список товаров.

Устранение неполадок

Вы: При вызове интерфейса списка товаров ошибка, код 429

Агент вызывает ozon_get_error_catalog({"code": "429"}) для получения описания ошибки ограничения частоты и решения, а также ozon_get_rate_limits({"operation_id": "ProductAPI_GetProductList"}) для просмотра конкретных правил ограничения частоты для этого интерфейса.

Разработка и тестирование

Установка зависимостей для разработки

uv sync --dev

Запуск тестов

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

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

Проверка кода

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

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

Запуск локального сервера

# 仅知识模式（无需凭据）
uv run ozon-mcp

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

Сборка Docker

docker build -t ozon-mcp:local .

Замечания по безопасности

• Не коммитьте файл .env. Все учётные данные передаются через переменные окружения, .env добавлен в .gitignore

• Не записывайте полные учётные данные в логи. Все поля с учётными данными защищены с помощью SecretStr, repr() и print() не раскроют фактические значения

• Используйте минимальные права. Рекомендуется создавать отдельный ключ API Ozon для MCP-сервера, выдавая только необходимые разрешения

• Регулярно меняйте ключи. Рекомендуется периодически обновлять ключи API в панели Ozon

• Операции записи требуют подтверждения. Все операции write и destructive требуют дополнительного параметра подтверждения

• Запускайте в доверенной среде. Рекомендуется запускать локально или на доверенном сервере, не открывайте доступ в интернет

• Сверяйтесь с правилами платформы. Правила ограничения частоты, требования к правам и тарифная политика Ozon API могут меняться

Часто задаваемые вопросы

MCP-клиент не находит службу

Убедитесь, что uv установлен и находится в PATH:

uv --version

Команда uv не найдена

Установите uv:

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

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

Переменные окружения не применяются

Убедитесь, что имена переменных используют префикс OZON_ и заданы корректно. Проверьте командой:

OZON_LOG_LEVEL=DEBUG uv run ozon-mcp --help

Ozon API возвращает 401 или 403

Проверьте правильность OZON_CLIENT_ID и OZON_API_KEY, убедитесь, что ключ не истёк.

Ограничение частоты запросов (429)

Сервер уже имеет встроенный механизм автоматических повторных попыток с экспоненциальной задержкой. Если ошибка 429 повторяется, снизьте частоту параллельных запросов.

Сбой запуска Docker

Убедитесь, что Docker установлен, а команда сборки выполняется из корневого каталога проекта:

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

Проблемы с путями в Windows

В конфигурации MCP-клиента используйте прямые или двойные обратные слэши:

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

Как настроить несколько магазинов

В текущей версии один процесс MCP-сервера соответствует одной учётной записи Ozon. Для нескольких магазинов необходимо запустить несколько экземпляров сервера с разными переменными окружения.

База знаний операций недоступна (knowledge_unavailable)

Если при запуске не удалось загрузить базу знаний операций (например, из-за повреждения или отсутствия файлов данных), три инструмента знаний операций по-прежнему существуют, но при вызове возвращают единую ошибку:

{
  "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。"
}

Описание возвращаемых полей:

Примечание: при недоступности базы знаний API-уровень знаний и другие инструменты продолжают正常工作, затрагивается только функция поиска знаний операций. После восстановления файлов базы знаний и перезапуска всё автоматически восстановится.

Лицензия

Данный проект распространяется по лицензии MIT License.

Отказ от ответственности

• Данный проект не является официальным проектом Ozon и не имеет отношения к Ozon

• Интерфейсы Ozon API, правила ограничения запросов, комиссионная политика и требования к правам доступа могут меняться в любое время

• Пользователи обязаны самостоятельно соблюдать условия обслуживания платформы Ozon и применимое законодательство

• При выполнении операций записи и операций с денежными средствами рекомендуется предварительно выполнять ручную проверку

• Данный проект не несёт ответственности за любые убытки, возникшие в результате использования данного программного обеспечения