ozon-seller

mcp-server-ozon-seller

适用于 Ozon Seller API 的 MCP 服务、CLI 工具和 Pydantic 模型库。

• MCP 服务 — 与 Claude Code、Claude Desktop 和其他 MCP 客户端集成
• CLI 工具 — 在终端中使用 API、编写脚本和实现自动化
• Pydantic 模型 — 可在自己的 Python 程序中使用的类型化 API 模型

所有数据都保留在您的计算机上，API 密钥不会传输到任何地方。

目录

• 架构
• 可用操作
• MCP 服务
  • 安装
  • 连接到 Claude Code
  • 连接到 Claude Desktop
  • 通过 --mcp-config 连接
  • 示例
• CLI 工具
  • 安装
  • 使用方法
  • 命令示例
• Pydantic 模型
  • 安装库
  • 在自己的程序中使用
• 环境变量
• 开发
• 许可证

架构

服务采用 搜索 + 执行 模式，而不是提供 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 密钥

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 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:

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