ozon-mcp-server

<div align="center">

![Русский](https://img.shields.io/badge/%D0%A0%D1%83%D1%81%D1%81%D0%BA%D0%B8%D0%B9-0A66C2?style=for-the-badge)
[![English](https://img.shields.io/badge/English-8B949E?style=for-the-badge)](README.en.md)
[![中文](https://img.shields.io/badge/%E4%B8%AD%E6%96%87-8B949E?style=for-the-badge)](README.zh.md)

</div>

# Ozon MCP Server

[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
[![MCP tools](https://img.shields.io/badge/MCP%20tools-151-orange.svg)](docs/tools.md)
[![Transport](https://img.shields.io/badge/transport-stdio%20%7C%20SSE-lightgrey.svg)](#как-это-устроено)
[![PyPI](https://img.shields.io/pypi/v/ozon-mcp-server.svg)](https://pypi.org/project/ozon-mcp-server/)

Управляйте магазинами Ozon прямо из чата с ИИ-ассистентом: цены, акции, реклама,
заказы, возвраты, отзывы, финансы — 151 инструмент поверх Ozon Seller API и
Performance API.
Для продавцов, у которых **несколько магазинов**: каждый вызов принимает `shop_id`,
ключи хранятся зашифрованными на вашем сервере, наружу ничего не уходит.
Отличие от прочих Ozon-MCP: покрыт не только Seller API, но и реклама, а
встроенная диагностика показывает, какие методы Ozon сломались, до того как это
заметит ассистент.

Торгуете ещё и на Wildberries? Есть такой же сервер для WB —
[wb-mcp-server](https://github.com/DeviceIngineering/wb-mcp-server).

Это личный рабочий инструмент автора: больше пяти месяцев ежедневной работы,
порядка двадцати кабинетов, 151 инструмент. Обновляется он по мере собственной
необходимости автора — подробности в разделе
[«Обновления и поддержка»](#обновления-и-поддержка).

```
Ты: Какие мои товары Ozon планирует затянуть в акцию?
Ты: Покажи расход по рекламным кампаниям за неделю и останови те, что тратят впустую.
Ты: У каких товаров индекс цены хуже, чем у конкурентов?
Ты: Ответь благодарностью на все новые отзывы с оценкой 5.
```

![Дашборд Ozon MCP Server](docs/img/dashboard.png)

## Что умеет

| Группа | Инструментов | Что внутри |
|--------|--------------|-----------|
| Акции и скидки | 14 | акции Ozon (список, кандидаты, вход/выход), собственные акции продавца, заявки «Хочу скидку» |
| Цены и ценовые стратегии | 14 | установка цен и минимальной цены, индекс цен, таймер минимальной цены, автостратегии по конкурентам |
| Реклама (Performance API) | 22 | кампании «Трафареты» (CPC), ставки и бюджеты, «Оплата за заказ» (CPO), статистика по товарам и дням |
| Товары | 21 | список и карточки, атрибуты, остатки, импорт и массовое обновление, медиа, архив, сертификаты |
| Заказы FBS и FBO | 17 | несобранные заказы, сборка (v4), этикетки, отмены, акты приёма-передачи, страна товара |
| Возвраты и отмены | 10 | единый список возвратов FBO+FBS, заявки rFBS с решением продавца, заявки на отмену |
| Отзывы, вопросы, чаты | 13 | отзывы и ответы, вопросы покупателей, переписка в чатах (v3) |
| Склады и отчёты | 8 | склады FBS, методы доставки, генерация и выгрузка отчётов |
| Финансы | 7 | баланс, транзакции, начисления, реализация, взаиморасчёты, движение денег |
| Категории, бренды, сертификаты | 7 | дерево категорий, атрибуты и их значения, сертификаты |
| Аналитика | 5 | аналитика по SKU, остатки и оборачиваемость, позиции товаров в поиске, топ поисковых запросов |
| Поставки FBO | 4 | заявки на поставку (v3), счётчики, таймслоты |
| Рейтинг | 2 | текущий рейтинг продавца и его история |
| Диагностика | 2 | самопроверка доступности Ozon API, детектор деградаций |
| Уведомления | 2 | подписки на push-вебхуки и справочник типов событий |
| Компания | 2 | данные продавца и тарифы |
| Магазины | 1 | список подключённых магазинов и их `shop_id` |

Полный нумерованный список с описанием каждого инструмента и его параметров —
в **[docs/tools.md](docs/tools.md)**. Он сгенерирован из `ozon_mcp/server.py`
(константа `TOOLS`) — то же самое отдаёт `tools/list` любому MCP-клиенту.

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

### Вариант 1: одна команда, без Docker

Сервер работает по stdio — так его подключают Claude Desktop, Cursor, VS Code и
другие MCP-клиенты. Ничего собирать не нужно:

```bash
uvx ozon-mcp-server
```

Или через pip:

```bash
pip install ozon-mcp-server
ozon-mcp
```

Конфигурация клиента (например, `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "ozon": {
      "command": "uvx",
      "args": ["ozon-mcp-server"],
      "env": {
        "OZON_CLIENT_ID": "ваш Client-Id",
        "OZON_API_KEY": "ваш API-ключ",
        "DATA_DIR": "~/.ozon-mcp"
      }
    }
  }
}
```

`DATA_DIR` укажите на любой доступный для записи каталог — там хранятся магазины,
ключи и статистика. По умолчанию используется `/data` (путь для Docker).

### Вариант 2: Docker с веб-интерфейсом

Нужен, если хотите дашборд, диагностику Ozon API и удобное добавление магазинов
через браузер. Пять команд:

```bash
git clone https://github.com/DeviceIngineering/ozon-mcp-server.git
cd ozon-mcp-server
cp .env.example .env               # для локальной сети можно оставить как есть
docker compose up -d --build       # соберёт образ и поднимет сервер на порту 8000
open http://localhost:8000/shops   # добавить магазин и ключи Ozon
```

Что делает каждый шаг:

- `.env` — все переменные необязательные. Ключи магазинов удобнее вводить в
  веб-интерфейсе, а не здесь. Единственное, что стоит задать сразу, если сервер
  виден не только вам, — `MCP_AUTH_TOKEN` (сгенерировать: `openssl rand -hex 32`).
- `docker compose up -d --build` — собирает образ из `Dockerfile`, пробрасывает
  порт `8000:8000` и создаёт том `ozon_data` для магазинов, ключей, статистики и
  истории диагностики. `restart: unless-stopped` поднимет контейнер после
  перезагрузки машины.
- `/shops` — форма добавления магазина: `shop_id` (латиницей, им вы будете
  оперировать в чате), название, Client-Id + Api-Key от Seller API и
  Client-Id + Client-Secret от Performance API. Кнопка «Проверить» делает живой
  запрос к Ozon и говорит, приняты ли ключи.

После запуска:

| Адрес | Что это |
|-------|---------|
| `http://localhost:8000/` | дашборд: счётчики вызовов, ошибки, деградации |
| `http://localhost:8000/shops` | магазины и ключи |
| `http://localhost:8000/diagnostics` | диагностика Ozon API |
| `http://localhost:8000/api/health` | health-эндпоинт, JSON |
| `http://localhost:8000/sse` | **эндпоинт MCP**, его и указывают клиентам |

Остановить: `docker compose down` (данные останутся в томе `ozon_data`).
Логи: `docker compose logs -f`.

### Без Docker

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install .
DATA_DIR=./data PORT=8000 ozon-mcp-web
```

`DATA_DIR` по умолчанию `/data` — при локальном запуске обязательно переопределите
его на доступный каталог.

## Установка в клиенты

Транспорт — SSE, адрес `http://<host>:8000/sse`. Поддержка SSE у клиентов разная:
часть понимает его напрямую, части нужен мост `mcp-remote`. По файлу-инструкции
на каждый клиент, с путями к конфигам под macOS, Linux, Windows и готовым JSON:

| Клиент | SSE напрямую | Инструкция |
|--------|--------------|------------|
| Claude Code | да | [docs/install-claude-code.md](docs/install-claude-code.md) |
| Claude Desktop | нет, мост `mcp-remote` | [docs/install-claude-desktop.md](docs/install-claude-desktop.md) |
| Cursor | да | [docs/install-cursor.md](docs/install-cursor.md) |
| Windsurf / Devin Desktop | да | [docs/install-windsurf.md](docs/install-windsurf.md) |
| VS Code (GitHub Copilot) | да | [docs/install-vscode-copilot.md](docs/install-vscode-copilot.md) |
| Cline | да | [docs/install-cline.md](docs/install-cline.md) |
| Continue.dev | да | [docs/install-continue.md](docs/install-continue.md) |
| Zed | не подтверждено, рекомендуем мост | [docs/install-zed.md](docs/install-zed.md) |
| JetBrains AI Assistant / Junie | да | [docs/install-jetbrains.md](docs/install-jetbrains.md) |
| Gemini CLI | да | [docs/install-gemini-cli.md](docs/install-gemini-cli.md) |
| OpenAI Codex CLI | нет, мост `mcp-remote` | [docs/install-codex.md](docs/install-codex.md) |

Самый короткий пример — Claude Code:

```bash
claude mcp add --transport sse ozon http://localhost:8000/sse \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"
```

Сводка по клиентам и справочник по мосту — [docs/README.md](docs/README.md).

## Мульти-магазин и безопасность

Кабинеты добавляются в веб-интерфейсе, каждый инструмент принимает обязательный
параметр `shop_id`; узнать доступные — инструментом `ozon_list_shops`. В чате это
выглядит так: «покажи остатки в магазине `alpha`».

Главная выгода не в самом переключении, а в том, что **стратегия пишется один раз
и раскатывается на все кабинеты**: правило по ценам, по ответам на отзывы или по
ставкам применяется ко всем магазинам сразу — без перелогинивания в кабинеты и без
копирования ключей по конфигам разных клиентов.

Цена такого подхода — общий IP. Все кабинеты ходят в Ozon с одного адреса: с того
сервера, где стоит MCP. Лимиты Ozon считаются в том числе по адресу, и чем больше
кабинетов и чем активнее по ним работают стратегии, тем ближе суммарный поток к
порогу, за которым начинается throttling или блокировка.

- ограничения на число магазинов в коде **нет**;
- реальный потолок задаёт не сервер, а лимиты Ozon на один IP;
- порядка двадцати кабинетов — оценка автора, при которой поток остаётся в
  безопасной зоне;
- дальше — разносить магазины по нескольким серверам с разными адресами.

Приближение к лимиту видно заранее, и как раз в веб-интерфейсе: растёт число
неудачных ping и предупреждений в диагностике, в статистике вызовов подскакивает
доля ошибок. Отличить одно от другого тоже можно по дашборду: массовый throttling
выглядит как одновременная деградация многих инструментов, поломка эндпоинта —
как деградация одного.

Как хранятся ключи:

- при первом обращении в `DATA_DIR` создаётся `.encryption_key` — ключ Fernet;
- ключи магазинов шифруются им и лежат в `DATA_DIR/shops.json`;
- в веб-интерфейсе ключи показываются замаскированными (`abc***xyz`), при
  сохранении маскированное значение не перезап