Ozon API MCP сервер

MCP (Model Context Protocol) сервер для Ozon Seller API и Ozon Performance API — по образцу Wildberries API MCP Server, тот же каркас (Express + JSON-RPC 2.0 поверх Streamable HTTP), но переписан под особенности Ozon.

Чем Ozon отличается от Wildberries (и почему код не 1:1)

Это отражено в коде: callOzon() — обычные вызовы Seller API с двумя заголовками, callPerf() — отдельный клиент с кешируемым OAuth-токеном для рекламы.

Related MCP server: io.github.dontsovcmc/ozon-seller

Инструменты (31 шт.)

Товары / остатки / цены

ozon_product_list, ozon_product_info, ozon_product_description, ozon_product_attributes, ozon_stocks_info, ozon_stocks_update (запись), ozon_prices_info, ozon_prices_update (запись), ozon_warehouse_list

Заказы FBS / FBO

ozon_fbs_postings_list, ozon_fbs_unfulfilled_list, ozon_fbs_posting_get, ozon_fbs_posting_cancel (запись, деструктивно), ozon_fbo_postings_list, ozon_fbo_posting_get

Финансы

ozon_finance_transactions, ozon_finance_transaction_totals, ozon_finance_realization, ozon_finance_summary (композитный: сам пагинирует /v3/finance/transaction/list и агрегирует)

Аналитика

ozon_analytics_data, ozon_analytics_stock_on_warehouses

Реклама (Performance API)

ozon_perf_campaign_list, ozon_perf_campaign_stats_request, ozon_perf_campaign_stats_result (отчёты асинхронные — запрос по UUID, потом опрос), ozon_perf_ads_summary (композитный: сам опрашивает отчёт с ограничением по попыткам)

Отзывы / вопросы / чат

ozon_reviews_list, ozon_review_info, ozon_review_comment_create (запись, публичный текст), ozon_chat_list, ozon_chat_history, ozon_chat_send_message (запись, публичный текст)

Важно: методы отзывов (ozon_reviews_*) требуют подписку Premium Plus в личном кабинете продавца Ozon — без неё Ozon вернёт ошибку доступа.

Установка и запуск

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

• Node.js ≥ 20

• Client-Id и Api-Key из личного кабинета Ozon Seller (Настройки → Seller API)

• (опционально, для рекламы) отдельные Client-Id/Client-Secret из Performance API — создаются в личном кабинете в разделе Продвижение → Performance API

Прямой запуск через Node.js

npm install
cp .env.example .env
# заполните OZON_CLIENT_ID / OZON_API_KEY (и опционально OZON_PERF_*) в .env
npm start

Сервер поднимется на порту 3000. MCP-эндпоинт: http://localhost:3000/mcp, health-check: http://localhost:3000/health.

Docker

cp .env.example .env
docker-compose up -d

Тесты и линтер

npm test
npm run lint

Пример запроса

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "ozon_product_list",
      "arguments": { "limit": 50 }
    }
  }'

Безопасность

• Ключи Ozon хранятся только в .env на сервере и никогда не уходят клиенту.

• MCP_API_KEY (опционально) защищает сам MCP-эндпоинт отдельным секретом — независимо от ключей Ozon.

• HTTPS в проде так же не терминируется сервером — нужен reverse-proxy.

• Контейнер запускается от непривилегированного пользователя (appuser).

• Инструменты с записью (*_update, *_cancel, *_comment_create, *_send_message) помечены аннотацией readOnlyHint: false (а ozon_fbs_posting_cancel — ещё и destructiveHint: true), чтобы клиенты MCP могли различать их и запрашивать подтверждение перед вызовом.

Известные ограничения / что стоит проверить перед продакшном

1. Точные пути Performance API (/api/client/campaign, /api/client/statistics) документированы Ozon хуже, чем Seller API, и периодически меняются — перед боевым использованием сверьте с актуальной документацией на docs.ozon.ru/api/performance.

2. ozon_finance_summary и ozon_perf_ads_summary — композитные инструменты, написанные по аналогии с wb_finance_summary/wb_ads_summary из оригинала; они не тестировались против боевого аккаунта Ozon (нет доступа к реальным кредам), только против структуры ответов из документации — обязательно прогоните на своих данных перед доверием к цифрам.

3. Список инструментов покрывает основные разделы Ozon Seller API, но не весь API целиком (у Ozon ~460 путей); при необходимости легко добавить новый инструмент по тому же паттерну: описание в tools[] + ветка в executeTool().