mcp-yandex-merchants

v1.0.0

Published

5 days ago

MCP server for the Yandex Merchants (Яндекс Товары) partner API — feed info, offer price updates, discounts, hiding and unhiding offers for AI agents.

Downloads

920

0High
0Medium
0Low

gistrec

mcp model-context-protocol yandex yandex-merchants yandex-products e-commerce product-feed price-management

Меняйте цены и видимость товаров обычной командой — без пересборки YML-фида

Яндекс Товары MCP — MCP-сервер, с которым Claude, Cursor, Codex и другие AI-клиенты обновляют цены, скидки и видимость офферов в Яндекс Товарах по обычной команде. Он работает поверх уже загруженного YML-фида: для точечного изменения не нужно редактировать и повторно отправлять весь файл.

9 готовых инструментов. Проверка доступа, список фидов, цены, скидки, скрытие, возобновление показа и универсальный raw_request.
Один товар или большая выборка. До 2 000 изменений цен и до 500 скрытий или возвратов в одном запросе.
Старая и специальная цена. Можно задать зачёркнутую базовую цену и отдельное предложение для Яндекс Пэй, СБП или карты Ozon.
Явный результат записи. Инструменты возвращают поле status из ответа API: OK означает успех, ERROR — ошибку операции; одного HTTP 200 недостаточно.
Записи не дублируются ретраями. После 5xx или обрыва связи автоматически повторяются только безопасные GET-запросы; 429 обрабатывается с задержкой.
Без глобальной установки. Пакет запускается через npx на Node.js 20+ и подключается к AI-клиенту по stdio.

Кому подходит: e-commerce-командам, которые уже передают YML-фид в Яндекс Товары и хотят быстро исправлять отдельные цены или видимость офферов из AI-клиента. Сервер не создаёт фиды, не заменяет кабинет и не умеет читать текущую цену или список скрытых товаров.

Если цена изменилась или товар закончился, полная пересборка фида добавляет лишнюю цепочку: найти источник, изменить выгрузку, загрузить её и дождаться обработки. MCP-сервер отправляет точечное изменение в партнёрский API. При этом он не притворяется системой учёта: API умеет записывать состояние офферов, но почти не позволяет читать его обратно.

Проверить доступ без изменений

Вы: Проверь токен и покажи доступные фиды. Ничего не меняй.
Ассистент: Вызову check_access и list_feeds, верну количество фидов, их id и URL.

Обновить цену с явным подтверждением

Вы: Подготовь изменение цены SKU-123 в фиде 1069 на 1 490 ₽ со старой ценой 1 990 ₽. Сначала покажи, что отправишь.
Ассистент: Покажу feed_id, offer_id, новую и зачёркнутую цену. set_offer_price вызову только после вашей следующей команды.

Скрыть закончившиеся товары

Вы: Скрой SKU-7 и SKU-8 из фида 1069. Это реальное изменение.
Ассистент: Отправлю оба оффера через hide_offers и проверю status в ответе API. Прочитать список скрытых офферов после записи этот API не позволяет.

Цена, скрытие и возобновление показа — реальные записи. Безопасный первый шаг — check_access или list_feeds. Все остальные специализированные инструменты изменяют данные в Яндекс Товарах.

Подключить сервер · Посмотреть сценарии · Открыть справочник инструментов

Увидеть работу за минуту

Вы: Проверь подключение и покажи мои фиды.
Ассистент: Токен работает, доступно два фида. Верну их feedId и URL; никаких записей не выполняю.
Вы: Для SKU-123 из нужного фида поставь цену 1 490 ₽ вместо 1 990 ₽. Перед записью проверь, что скидка попадает в допустимый диапазон.
Ассистент: Скидка валидна. После подтверждения отправлю одну запись и признаю её успешной только при status: "OK".
Вы: Товар закончился. Скрой его до отдельной команды на возврат.
Ассистент: Вызову hide_offer без TTL. Когда товар вернётся, отдельный show_offers возобновит показ.

Примеры показывают последовательность доступных инструментов. Реальные фиды, результаты операций и доступность офферов всегда определяются вашим аккаунтом и ответами API Яндекс Товаров.

Содержание

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

Нужны Node.js 20+, загруженный в Яндекс Товары YML-фид и OAuth-токен со scope products:partner-api.

Получите OAuth-токен под тем же логином, который загрузил фид.

Добавьте MCP-сервер в Codex:

codex mcp add yandex-merchants \
  --env YANDEX_MERCHANTS_OAUTH_TOKEN=ваш_токен \
  -- npx -y mcp-yandex-merchants@latest

Начните новую задачу Codex и проверьте подключение запросом без записи:
Проверь доступ к API Яндекс Товаров и покажи мои фиды. Ничего не изменяй.

Для Claude Code, Claude Desktop, Cursor и VS Code готовые конфигурации находятся в разделе «Установка в другие AI-клиенты».

Что можно поручить

Проверить токен и найти фид

Проверить подключение. Получить ответ { ok, feedsCount } без изменения данных — check_access.
Посмотреть доступные фиды. Получить feedId и URL каждого фида — list_feeds.

feed_id нужен для любой записи. API не возвращает состав, статус или текущие значения офферов внутри фида.

Обновить цены

Изменить один оффер. Передать новую цену, необязательную зачёркнутую цену и условия специальной оплаты — set_offer_price.
Обновить выборку. Отправить от 1 до 2 000 офферов одним вызовом — update_offer_prices.
Поставить скидку. Задать новую и старую цену; диапазон скидки 5–95 % проверяется до запроса — set_offer_discount.

Все цены отправляются в рублях с currencyId: "RUR". Если в одном фиде несколько предложений имеют одинаковый id, API обновляет только первое.

Скрыть или вернуть товары

Скрыть один оффер. Убрать закончившийся товар из поиска — hide_offer.
Скрыть выборку. Передать от 1 до 500 офферов одним вызовом — hide_offers.
Возобновить показ. Вернуть до 500 ранее скрытых офферов — show_offers.

Скрытие может быть бессрочным или содержать ttl_in_hours до 720 часов. Поскольку описание сериализации TTL в официальной документации неполное, при сбое используйте скрытие без срока и отдельный show_offers.

Вызвать остальные методы API

raw_request вызывает относительный путь партнёрского API Яндекс Товаров с методом GET, POST или DELETE. Тело запроса передаётся в исходном wire-формате API.

raw_request помечен как разрушительный инструмент. Он способен выполнять произвольную запись. Используйте специализированный инструмент, если он уже есть.

Полные входные схемы, коды ошибок и форматы ответов собраны в справочнике инструментов.

Где изменяются данные

Партнёрский API Яндекс Товаров — write-mostly API. Из трёх ресурсов только feeds-info читает данные; цены и видимость записываются без возможности проверить текущее состояние тем же API.

| Действие | Что происходит | Изменяет офферы | |---|---|---:| | check_access, list_feeds | Проверяет токен и читает id с URL фидов | Нет | | set_offer_price, set_offer_discount | Меняет цену одного оффера | Да | | update_offer_prices | Меняет цены 1–2 000 офферов | Да | | hide_offer, hide_offers | Скрывает один или несколько офферов | Да | | show_offers | Возобновляет показ скрытых офферов | Да | | raw_request | Выполняет произвольный поддерживаемый вызов API | Зависит от метода |

Что сервер делает для снижения риска:

Проверяет входные лимиты, длину id, положительные цены и диапазон скидки до обращения к API.
Возвращает тело ответа без потери поля status, чтобы AI-клиент мог отличить OK от ERROR, даже если HTTP-ответ имеет код 200.
Не повторяет автоматически запись после 5xx или сетевой ошибки, чтобы не дублировать неидемпотентную операцию.
Ограничивает raw_request хостом Merchants API, чтобы OAuth-токен не ушёл на посторонний адрес.
Передаёт AI-клиенту MCP-аннотации чтения, записи, идемпотентности и разрушительности.

Поведение подтверждений задаёт AI-клиент, а не MCP-сервер. Если хотите сначала увидеть изменение, прямо попросите ассистента показать feed_id, offer_id и новые значения, но не вызывать инструмент до подтверждения.

Установка в другие AI-клиенты

codex mcp add yandex-merchants \
  --env YANDEX_MERCHANTS_OAUTH_TOKEN=ваш_токен \
  -- npx -y mcp-yandex-merchants@latest

После подключения начните новую задачу и сначала запустите check_access без изменений.

claude mcp add yandex-merchants \
  -e YANDEX_MERCHANTS_OAUTH_TOKEN=ваш_токен \
  -- npx -y mcp-yandex-merchants@latest

Откройте claude_desktop_config.json: на macOS он находится в ~/Library/Application Support/Claude/, на Windows — в %APPDATA%\Claude\.

{
  "mcpServers": {
    "yandex-merchants": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-merchants@latest"],
      "env": {
        "YANDEX_MERCHANTS_OAUTH_TOKEN": "ваш_токен"
      }
    }
  }
}

Добавьте сервер в ~/.cursor/mcp.json или в .cursor/mcp.json проекта:

{
  "mcpServers": {
    "yandex-merchants": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-merchants@latest"],
      "env": {
        "YANDEX_MERCHANTS_OAUTH_TOKEN": "ваш_токен"
      }
    }
  }
}

Создайте .vscode/mcp.json. Здесь используется ключ servers, а не mcpServers:

{
  "servers": {
    "yandex-merchants": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-merchants@latest"],
      "env": {
        "YANDEX_MERCHANTS_OAUTH_TOKEN": "ваш_токен"
      }
    }
  }
}

Получение доступа к API

Зарегистрируйте приложение на oauth.yandex.ru/client/new: платформа «Веб-сервисы», Redirect URI https://oauth.yandex.ru/verification_code.
Добавьте доступ products:partner-api — «API поиска по товарам».
Откройте https://oauth.yandex.ru/authorize?response_type=token&client_id=<ClientID> под логином, который загрузил YML-фид.
Передайте полученный токен серверу в YANDEX_MERCHANTS_OAUTH_TOKEN.
Проверьте подключение инструментом check_access.

Логин токена должен совпадать с логином, под которым загружен фид. Иначе API не вернёт доступные фиды. После подтверждения прав на сайт в Вебмастере доступ к API может появиться не сразу.

Токен хранится открытым текстом в конфигурации AI-клиента. Относитесь к нему как к паролю и не добавляйте конфиг с реальным токеном в Git.

Настройка

| Переменная | Обязательна | По умолчанию | Что задаёт | |---|---:|---|---| | YANDEX_MERCHANTS_OAUTH_TOKEN | да | — | OAuth-токен со scope products:partner-api | | YANDEX_MERCHANTS_BASE_URL | нет | https://yandex.ru/products/api/ext/partner | Корневой URL API | | YANDEX_MERCHANTS_TIMEOUT_MS | нет | 60000 | Таймаут одного запроса, мс | | YANDEX_MERCHANTS_MAX_RETRIES | нет | 3 | Повторы при 429; для 5xx и сетевых ошибок — только GET-запросы | | ASKADS_TELEMETRY | нет | включена | 0, false, off или no отключает анонимную телеметрию |

Данные и телеметрия

Запросы к Яндекс Товарам

Сервер запускается на вашей машине и обращается к https://yandex.ru/products/api/ext/partner напрямую. OAuth-токен добавляется только к запросам этого API. Даже raw_request принимает относительный путь: переход на посторонний хост блокируется.

Анонимная телеметрия

По умолчанию сервер отправляет на usage.gistrec.cloud три вида технических событий: запуск сервера, имя вызванного инструмента и код причины неудачного запуска.

В событие входят случайный идентификатор установки, версия пакета, имя и версия AI-клиента, версия Node.js и операционная система. OAuth-токен, данные аккаунта, id фидов и офферов, цены, аргументы инструментов и тексты запросов не читаются и не отправляются. Отправка выполняется в фоне с таймаутом 2 секунды и не влияет на работу сервера.

Чтобы отключить телеметрию для MCP-серверов Ask Ads, добавьте:

ASKADS_TELEMETRY=0

Реализация находится в src/telemetry.ts.

Ограничения

Это write-mostly API. Безопасно читать можно только список фидов; цена и видимость оффера меняются в рабочем аккаунте.
Нет чтения текущего состояния. API не возвращает текущие цены, скрытые предложения, содержимое или статус фида. Ведите журнал изменений на своей стороне.
Нет управления фидами. Создать, удалить или перезагрузить YML-фид можно только в кабинете или Вебмастере.
Только рубли. Клиент всегда передаёт currencyId: "RUR"; другие валюты API не принимает.
Ограничена длина offer id. Идентификатор предложения должен быть не длиннее 50 символов.
Ограничены батчи. До 2 000 цен и до 500 скрытий или возобновлений показа в одном запросе.
Rate limits. До 50 000 изменений цен в минуту и суммарно до 50 000 скрытий и возобновлений показа в минуту.
Нет автоматического отката. После сетевого обрыва у записи может не быть однозначного результата, а проверить его чтением через этот API нельзя.

Документация и разработка

Все инструменты — входные данные, ответы, коды ошибок и ограничения.
Разработка — локальный запуск, тесты, сборка и read-only smoke-проверка.
Публикация — выпуск npm-пакета и листинг в каталогах MCP.
npm-пакет — опубликованная версия mcp-yandex-merchants.
API Яндекс Товаров — официальная документация.

Проверить проект локально:

npm install
npm run typecheck
npm test

Тесты не обращаются к сети. npm run smoke — отдельная живая read-only проверка с реальным токеном.

Помощь и обратная связь

Нашли ошибку или не хватает сценария? Создайте issue или напишите в Telegram: @gistrec.

Лицензия

MIT — см. LICENSE.