ozon-mcp

MCP-сервер для API Ozon Seller и Performance. Подключите любого AI-агента к своему кабинету Ozon за считанные минуты.

ozon-mcp — это насыщенный знаниями MCP-сервер, который превращает весь инструментарий продавца Ozon в 15 высокоэффективных инструментов. AI-агенты (Claude, Cursor, Cline, Continue, Goose, Zed и др.) могут искать методы API на русском или английском языках, изучать любой из 466 методов с полностью разрешенной JSON-схемой и выполнять вызовы со встроенными средствами защиты. Поддерживает уровни подписки, автоматическую пагинацию для всех 4 стилей курсоров, повторные попытки при ошибках 429 и 13 готовых к использованию аналитических рабочих процессов.

Ключевые факты: 466 индексированных методов (420 Seller + 46 Performance), 55 разделов, смоделировано 5 уровней подписки, 38 эндпоинтов с автоматической пагинацией, 43 деструктивных метода с двойным подтверждением, 13 готовых рабочих процессов для типичных сценариев продавца.

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

Предварительные требования

• Python 3.12 или 3.13

• Менеджер пакетов uv — установите с помощью curl -LsSf https://astral.sh/uv/install.sh | sh

• Учетные данные Ozon Seller API (Client-Id + Api-Key) — получите их на https://seller.ozon.ru/app/settings/api-keys

Установка

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

Проверка работы

uv run ozon-mcp --help

Вы должны увидеть строку использования FastMCP. Сервер использует протокол MCP stdio — укажите на него любому совместимому клиенту (инструкции ниже).

Related MCP server: Avito MCP

Подключение к вашему AI-агенту

ozon-mcp использует стандартный транспорт MCP stdio. Каждый пример ниже предоставляет одни и те же 15 инструментов — выберите тот клиент, который вы уже используете.

Claude Desktop

Отредактируйте: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %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

Или добавьте в ~/.claude/mcp.json с той же структурой, что и в конфигурации Claude Desktop выше.

Cursor

Настройки → MCP → Добавить новый MCP-сервер, или отредактируйте ~/.cursor/mcp.json:

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

Windsurf

Отредактируйте ~/.codeium/windsurf/mcp_config.json:

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

Cline (расширение для VS Code)

Cline → Настройки → MCP-серверы → Добавить:

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

Continue.dev

Отредактируйте ~/.continue/config.json:

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

Goose, Zed или любой другой MCP-клиент

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

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

Ознакомьтесь с официальным списком MCP-клиентов на https://modelcontextprotocol.io/clients.

Примеры использования

Все примеры ниже показывают реалистичные ответы, скопированные из tests/fixtures/responses/ — анонимизированные идентификаторы (99000001, TEST-SKU-001), но реальная структура.

Пример 1 — Получение всех ваших товаров

Вы: Используйте ozon_fetch_all с operation_id="ProductAPI_GetProductList" чтобы получить все мои товары.

Агент вызывает:

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

Сервер автоматически проходит по курсору last_id и возвращает:

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

Пример 2 — Поиск товаров с риском отсутствия на складе

Вы: Запустите рабочий процесс oos_risk_analysis для моего кабинета.

Агент сначала изучает рабочий процесс:

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

→ говорит агенту вызвать AnalyticsAPI_StocksTurnover (ограничение скорости 1 запрос/мин — очередь сервера для каждого эндпоинта обрабатывает это за вас) и как интерпретировать turnover_grade. Вызов возвращает:

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

Поле interpret рабочего процесса говорит агенту пометить SKU, где idc < 14 или turnover_grade ∈ {DEFICIT, NO_SALES}, и вывести их, отсортировав по idc asc.

Пример 3 — Полная проверка состояния кабинета

Вы: Проверьте состояние моего кабинета Ozon с помощью рабочего процесса cabinet_health_check.

Рабочий процесс говорит агенту прочитать три эндпоинта параллельно — RatingAPI_RatingSummaryV1, SellerAPI_SellerInfo, AverageDeliveryTimeSummary. Первый вызов возвращает:

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

Пример 4 — Анализ цен на товары

Вы: У каких моих товаров красный индекс цены?

Агент запускает рабочий процесс pricing_analysis и проверяет поле price_indexes.color_index для каждого товара:

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

Список common_mistakes в рабочем процессе напоминает агенту сравнивать с marketing_seller_price (фактическая цена для покупателя), а не только с базовой price.

Пример 5 — Аудит контента

Вы: Найдите товары с низким рейтингом контента и скажите мне, что улучшить.

Агент запускает content_audit, получает рейтинги для каждого SKU + список атрибутов, которые повысят оценку:

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

Рабочий процесс говорит агенту, что повышение rating на +10 заметно улучшает ранжирование в поиске — поэтому заполнение этих двух атрибутов дает около 4 баллов.

Доступные инструменты (15)

Готовые рабочие процессы (13)

Рабочие процессы — это готовые пошаговые рецепты. Используйте ozon_get_workflow("name") для получения полного плана, включая interpret, when_to_use, common_mistakes и рекомендуемую схему БД для рабочих процессов типа синхронизации.

Покрытие API

Смоделированные уровни подписки (низкий → высокий): LITE → STANDARD → PREMIUM → PREMIUM_PLUS → PREMIUM_PRO.

Ключевые особенности

Учет подписки

Сервер знает, какие методы ограничены премиум-уровнями, и отклоняет вызов до того, как он покинет вашу машину — это экономит вашу квоту 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
}

Управление лимитами (Rate-limit)

• Автоматический повтор с экспоненциальной задержкой при ошибке 429.

• Учитывает Retry-After (как дельта-секунды, так и дату HTTP RFC 7231).

• Семафор для каждого эндпоинта для медленных методов (например, /v1/analytics/turnover/stocks жестко ограничен 1 запросом в минуту на стороне Ozon — сервер автоматически ставит параллельные вызовы в очередь).

Автоматическая пагинация

ozon_fetch_all обрабатывает все четыре шаблона пагинации, используемые Ozon: offset/limit, cursor, last_id, page_number. Он также обнаруживает редкие случаи, когда сервер возвращает один и тот же курсор дважды подряд, и прерывает цикл вместо бесконечного ожидания.

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}

Единый конверт ошибок

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

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

Классификация безопасности в каталоге

Каждый метод имеет поле safety — read, write или destructive. Для write требуется confirm_write=True; для деструктивных методов требуется и confirm_write=True, И i_understand_this_modifies_data=True. Эвристики из экстрактора схем подкреплены 43 кураторскими записями safety_warning в quirks.yaml, поэтому агент всегда видит четкое напоминание перед изменением чего-либо.

Поддержание спецификаций API в актуальном состоянии

Ozon периодически обновляет свой swagger. Для синхронизации:

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

Запустите ozon_get_swagger_meta, чтобы подтвердить, что встроенный снимок свежий (CI также проваливает сборку, если снимок старше 14 дней).

Разработка

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

См. CONTRIBUTING.md для получения информации о том, как добавлять знания (рабочие процессы, примеры, особенности, переопределения подписки).

Лицензия

MIT