mcp-server-ozon-seller

![Version](https://github.com/dontsovcmc/mcp-server-ozon-seller)

MCP-сервер, CLI-утилита и библиотека Pydantic-моделей для Ozon Seller API.

MCP-сервер — интеграция с Claude Code, Claude Desktop и другими MCP-клиентами
CLI-утилита — работа с API из терминала, скрипты и автоматизация
Pydantic-модели — типизированные модели API для использования в своих Python-программах

Все данные остаются на вашем компьютере — ключи API никуда не передаются.

Архитектура
Доступные действия
MCP-сервер
Установка
Подключение к Claude Code
Подключение к Claude Desktop
Подключение через --mcp-config
Примеры
CLI-утилита
Установка
Использование
Примеры команд
Pydantic-модели
Установка
Использование в своих программах
Переменные окружения
Разработка
Лицензия

Архитектура

Сервер использует паттерн search + execute — вместо 111 отдельных инструментов предоставляет 3:

| Инструмент | Описание | |------------|----------| | ozon_search | Поиск действий по описанию на естественном языке | | ozon_execute | Выполнение действия по ID | | ozon_execute_file | Выполнение действия со скачиванием файла |

Как это работает

LLM: ozon_search("отменить отправление fbs")
→ [{"id": "fbs-posting-cancel", "params_schema": {"posting_number": "str", ...}, ...}]

LLM: ozon_execute("fbs-posting-cancel", '{"posting_number": "12345678-0001-1", "cancel_reason_id": 352}')
→ {"result": true}

Доступные действия (111)

| Домен | Кол-во | Описание | |-------|--------|----------| | products | 21 | Товары: создание, обновление, цены, остатки, атрибуты | | fbs | 17 | FBS-отправления: списки, отмены, этикетки, акты | | fbo | 9 | FBO: отправления, поставки, склады | | categories | 4 | Категории и атрибуты товаров | | finance | 4 | Финансы: транзакции, итоги, движение средств | | analytics | 3 | Аналитика: данные, остатки, оборачиваемость | | warehouses | 2 | Склады и способы доставки | | returns | 8 | Возвраты FBO/FBS/rFBS | | chats | 6 | Чаты с покупателями | | promos | 6 | Акции и промо | | strategies | 4 | Ценовые стратегии | | rating | 3 | Рейтинг и качество продавца | | reports | 4 | Отчёты | | reviews | 4 | Отзывы покупателей | | questions | 3 | Вопросы покупателей | | cancellations | 4 | Заявки на отмену | | certificates | 6 | Сертификаты | | barcodes | 2 | Штрихкоды | | brands | 1 | Бренды |

---

MCP-сервер

Установка

Шаг 1. Получить API-ключи

Войдите в Ozon Seller
Перейдите в Настройки → API-ключи
Создайте ключ (Admin)
Скопируйте Client-Id и Api-Key

Шаг 2. Подключить MCP-сервер

Подключение к Claude Code

Способ 1: через uvx (не требует установки пакета)

Требуется uv — если не установлен: ``bash curl -LsSf https://astral.sh/uv/install.sh | sh ``

claude mcp add ozon-seller \
  -e OZON_CLIENT_ID=ваш_client_id \
  -e OZON_API_KEY=ваш_api_key \
  -- uvx mcp-server-ozon-seller

Способ 2: через pip

pip install mcp-server-ozon-seller

claude mcp add ozon-seller \
  -e OZON_CLIENT_ID=ваш_client_id \
  -e OZON_API_KEY=ваш_api_key \
  -- mcp-server-ozon-seller

Для удаления: ``bash claude mcp remove ozon-seller ``

Подключение к Claude Desktop

Добавьте в конфигурационный файл:

| Клиент | ОС | Путь к файлу | |--------|----|-------------| | Claude Code | все | ~/.claude/settings.json (секция mcpServers) | | Claude Desktop | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Claude Desktop | Windows | %APPDATA%\Claude\claude_desktop_config.json | | Claude Desktop | Linux | ~/.config/Claude/claude_desktop_config.json |

Через uvx: ``json { "mcpServers": { "ozon-seller": { "command": "uvx", "args": ["mcp-server-ozon-seller"], "env": { "OZON_CLIENT_ID": "ваш_client_id", "OZON_API_KEY": "ваш_api_key" } } } } ``

Через pip (после pip install mcp-server-ozon-seller): ``json { "mcpServers": { "ozon-seller": { "command": "mcp-server-ozon-seller", "env": { "OZON_CLIENT_ID": "ваш_client_id", "OZON_API_KEY": "ваш_api_key" } } } } ``

Подключение через --mcp-config

Подключает сервер только на время одной сессии Claude, не сохраняя в настройки. Токен хранится в отдельном .env.mcp файле, а не в конфиге Claude.

Из JSON-строки: ``bash claude --mcp-config '{"ozon-seller":{"command":"bash","args":["-c","source ~/.env.mcp && exec uvx mcp-server-ozon-seller"]}}' ``

Из файла: ``bash claude --mcp-config ~/mcp-servers.json ``

Пример ~/mcp-servers.json: ``json { "ozon-seller": { "command": "bash", "args": ["-c", "source ~/.env.mcp && exec uvx mcp-server-ozon-seller"] } } ``

Пример ~/.env.mcp: `` OZON_CLIENT_ID=ваш_client_id OZON_API_KEY=ваш_api_key ``

Шаг 3. Проверить

Попросите Claude: «покажи мои товары на Ozon» — он вызовет ozon_search, затем ozon_execute.

Примеры (MCP)

«покажи мои товары на Ozon» → ozon_search("products list") → ozon_execute("product-list")
«отмени FBS отправление 12345678-0001-1» → ozon_execute("fbs-posting-cancel", ...)
«скачай акт приёмки №42» → ozon_execute_file("fbs-act-pdf", ...)
«какие FBS заказы ещё не собраны?» → ozon_execute("fbs-postings-list", ...)
«покажи финансовые транзакции за апрель» → ozon_execute("finance-transactions", ...)

---

CLI-утилита

Установка (CLI)

pip install mcp-server-ozon-seller

Переменные окружения OZON_CLIENT_ID и OZON_API_KEY должны быть установлены:

export OZON_CLIENT_ID=ваш_client_id
export OZON_API_KEY=ваш_api_key

Или через файл:

ozon-seller-cli --env /path/to/.env <command>

Формат файла — KEY=VALUE, по одной переменной на строку, #-комментарии.

Использование (CLI)

Без аргументов запускается MCP-сервер, с командой — CLI. Все команды выводят JSON.

# Версия
ozon-seller-cli --version

# Справка
ozon-seller-cli --help
ozon-seller-cli <command> --help

Примеры команд

# Товары
ozon-seller-cli product-list --limit 10
ozon-seller-cli product-info --offer-id SKU-001
ozon-seller-cli product-stocks-info

# FBS-отправления
ozon-seller-cli fbs-list
ozon-seller-cli fbs-cancel-reasons
ozon-seller-cli fbs-label 12345678-0001-1

# FBO
ozon-seller-cli fbo-list
ozon-seller-cli fbo-supply-list

# Финансы и аналитика
ozon-seller-cli finance-transactions '{"date": {"from": "2026-04-01", "to": "2026-04-25"}}'
ozon-seller-cli analytics-stock

# Возвраты
ozon-seller-cli returns-fbs
ozon-seller-cli returns-fbo

# Другое
ozon-seller-cli warehouses
ozon-seller-cli categories
ozon-seller-cli rating
ozon-seller-cli reviews
ozon-seller-cli brands

---

Pydantic-модели

Пакет содержит типизированные Pydantic-модели всех объектов API. Модели можно использовать в своих Python-программах для валидации данных и автодополнения в IDE.

Установка (библиотеки)

pip install mcp-server-ozon-seller

Использование в своих программах

from mcp_server_ozon_seller.models import FbsPostingsListParams

# Валидация данных
params = FbsPostingsListParams.model_validate({
    "filter_dict": {"status": "awaiting_packaging"},
    "limit": 50,
})
print(params.model_dump_json())

# Создание объекта
params = FbsPostingsListParams(limit=10)
print(params.limit)  # type-safe доступ к полям

Все модели используют extra="allow" для forward compatibility — неизвестные поля API не вызывают ошибок.

Полный список моделей: models.py

---

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

| Переменная | Обязательная | По умолчанию | Описание | |------------|:------------:|:------------:|----------| | OZON_CLIENT_ID | да | — | Client-Id из личного кабинета Ozon Seller | | OZON_API_KEY | да | — | Api-Key из личного кабинета Ozon Seller | | OZON_TIMEOUT | нет | 30 | Таймаут HTTP-запросов к API (секунды) | | OZON_FILE_TIMEOUT | нет | 60 | Таймаут скачивания файлов (секунды) |

Получить ключи: Ozon Seller → Настройки → API-ключи.

Разработка

pip install -e ".[test]"
ruff check src/ tests/
pytest tests/ -v

Лицензия

MIT

mcp-server-ozon-seller