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

<img src="./assets/a1-logo.svg" alt="A1" width="22"> Яндекс Товары 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 Яндекс Товаров.

---

Содержание

• Быстрый старт
• Что можно поручить
• Где изменяются данные
• Установка в другие AI-клиенты
• Получение доступа к API
• Настройка
• Данные и телеметрия
• Ограничения
• Документация и разработка
• Помощь и обратная связь

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

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

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

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

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

3. Начните новую задачу 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-клиенты

<details open> <summary><strong>Codex</strong></summary>

<br>

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

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

</details>

<details> <summary><strong>Claude Code</strong></summary>

<br>

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

</details>

<details> <summary><strong>Claude Desktop</strong></summary>

<br>

Откройте 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": "ваш_токен"
      }
    }
  }
}

</details>

<details> <summary><strong>Cursor</strong></summary>

<br>

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

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

</details>

<details> <summary><strong>VS Code</strong></summary>

<br>

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

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

</details>

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

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