Back to Directory/Analytics & BI

io.github.dontsovcmc/ozon-seller

MCP server for Ozon Seller API — products, FBS/FBO, finance, analytics, returns

Analytics & BIPythonv0.3.1
View on GitHub

mcp-server-ozon-seller

Version

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

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

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

Оглавление

Архитектура

Сервер использует паттерн 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)

ДоменКол-воОписание
products21Товары: создание, обновление, цены, остатки, атрибуты
fbs17FBS-отправления: списки, отмены, этикетки, акты
fbo9FBO: отправления, поставки, склады
categories4Категории и атрибуты товаров
finance4Финансы: транзакции, итоги, движение средств
analytics3Аналитика: данные, остатки, оборачиваемость
warehouses2Склады и способы доставки
returns8Возвраты FBO/FBS/rFBS
chats6Чаты с покупателями
promos6Акции и промо
strategies4Ценовые стратегии
rating3Рейтинг и качество продавца
reports4Отчёты
reviews4Отзывы покупателей
questions3Вопросы покупателей
cancellations4Заявки на отмену
certificates6Сертификаты
barcodes2Штрихкоды
brands1Бренды

MCP-сервер

Установка

Шаг 1. Получить API-ключи
  1. Войдите в Ozon Seller
  2. Перейдите в Настройки → API-ключи
  3. Создайте ключ (Admin)
  4. Скопируйте Client-Id и Api-Key
Шаг 2. Подключить MCP-сервер

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

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

Требуется uv — если не установлен:

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

Для удаления:

claude mcp remove ozon-seller

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

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

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

Через uvx:

{
  "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):

{
  "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-строки:

claude --mcp-config '{"ozon-seller":{"command":"bash","args":["-c","source ~/.env.mcp && exec uvx mcp-server-ozon-seller"]}}'

Из файла:

claude --mcp-config ~/mcp-servers.json

Пример ~/mcp-servers.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

Installation

Source-derived launch command. Check the maintainer’s required arguments and credentials before running:

bash
uvx mcp-server-ozon-seller

Set up in your AI client

Merge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.

json
{
  "mcpServers": {
    "io-github-dontsovcmc-ozon-seller": {
      "command": "uvx",
      "args": [
        "mcp-server-ozon-seller"
      ]
    }
  }
}

Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.

Claude Desktop setup reference

Package

mcp-server-ozon-sellerpypi

Compatible MCP Clients

io.github.dontsovcmc/ozon-seller works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.

  • Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.
  • Cursor~/.cursor/mcp.jsonRestart Cursor for changes to take effect.
  • VS Code.vscode/mcp.jsonReload VS Code window for changes to take effect.
  • Windsurf~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect.
  • Claude Code.mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.

Learn More

Google Analytics MCP Server: Ask GA4 Questions DirectlyGA4's reporting interface is powerful but slow to use for a quick question. A Google Analytics MCP server lets Claude query your GA4 property directly, so 'how did organic traffic do last week' gets answered in one message instead of a five-click report build.Read articlePostHog MCP Server: Product Analytics for AI AgentsPostHog folded its MCP server into its main monorepo earlier this year, a consolidation move rather than a shutdown. This guide covers what the server actually exposes, how product analytics differs from the observability MCP servers MCPFind already covers, and what to check before connecting an agent to production analytics data.Read articleClickHouse MCP Server Guide for Analytics and OLAPClickHouse ships a first-party MCP server that queries both ClickHouse Cloud and self-hosted instances, read-only by default, with writes gated behind explicit env vars. This guide covers install, auth, tool names, and where it fits next to Snowflake.Read article