# A1 Яндекс Товары MCP [![npm](https://img.shields.io/npm/v/mcp-yandex-merchants)](https://www.npmjs.com/package/mcp-yandex-merchants) [![Glama](https://glama.ai/mcp/servers/A1-x-Tech/mcp-yandex-merchants/badges/score.svg)](https://glama.ai/mcp/servers/A1-x-Tech/mcp-yandex-merchants) [![CI](https://github.com/A1-x-Tech/mcp-yandex-merchants/actions/workflows/ci.yml/badge.svg)](https://github.com/A1-x-Tech/mcp-yandex-merchants/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE) **A1 Яндекс Товары MCP** подключает AI-приложение к партнёрскому API [Яндекс Товаров](https://merchants.yandex.ru). Можно обычными словами менять цены, скидки и видимость отдельных товаров — без редактирования и повторной загрузки всего YML-фида. Подключение начинается прямо в диалоге: не нужно заранее создавать токен или редактировать конфигурацию. - **13 готовых действий.** Подключение аккаунта прямо из диалога, проверка доступа, список фидов, цены, скидки, скрытие и возврат товаров, а также прямой вызов остальных методов API. - **Для одного товара и больших списков.** За один запрос можно изменить цены у 2 000 товаров или скрыть и вернуть до 500 товаров. - **Точечные изменения.** Сервер работает с уже загруженным YML-фидом и не создаёт фиды заново. - **Проверяемый результат.** Запись считается успешной только при `status: "OK"` в ответе Яндекс Товаров. - **Работает локально.** Сервер запускается через `npx`; OAuth-токен остаётся на вашем компьютере. Попробуйте первым сообщением: > Проверь подключение к Яндекс Товарам и покажи доступные фиды. [Подключить сервер](#быстрый-старт) · [Посмотреть сценарии](#что-можно-поручить) · [Открыть техническую документацию](#техническая-документация) --- ## Увидеть работу за минуту > **Вы:** Проверь подключение и покажи мои фиды. > > **Ассистент:** Проверяет токен и показывает `feedId` и адрес каждого доступного фида. > > **Вы:** В фиде 1069 подготовь новую цену для SKU-123: 1 490 ₽ вместо 1 990 ₽. Сначала покажи изменение. > > **Ассистент:** Подготовлено: фид 1069, товар SKU-123, новая цена 1 490 ₽, зачёркнутая цена 1 990 ₽. Отправить изменение? > > **Вы:** Да, обнови. > > **Ассистент:** Отправляет изменение и проверяет поле `status` в ответе. Операция завершена, если Яндекс Товары вернули `status: "OK"`. ## Содержание - [Быстрый старт](#быстрый-старт) - [Что можно поручить](#что-можно-поручить) - [Как это работает](#как-это-работает) - [Что может изменить данные](#что-может-изменить-данные) - [Подключение и настройка](#подключение-и-настройка) - [Данные и телеметрия](#данные-и-телеметрия) - [Ограничения](#ограничения) - [Техническая документация](#техническая-документация) - [Поддержка](#поддержка) ## Быстрый старт Понадобятся Node.js 20 или новее, загруженный в Яндекс Товары YML-фид и логин Яндекса, под которым этот фид загружен. Сервер запускается через `npx`, поэтому отдельно устанавливать пакет не требуется. 1. Добавьте сервер в AI-приложение — ниже открыт пример для Codex, остальные приложения собраны в сворачиваемые инструкции. 2. Напишите: «Подключи Яндекс Товары». Ассистент даст ссылку на вход в Яндекс и попросит прислать код подтверждения. Если вы задали `YANDEX_MERCHANTS_OAUTH_TOKEN` в конфигурации, этот шаг не нужен. 3. Проверьте подключение: «Проверь подключение к Яндекс Товарам и покажи доступные фиды». Если сервер вернул список фидов, можно переходить к ценам и видимости товаров.
Codex
**Через интерфейс приложения:** 1. Откройте **Settings → MCP servers**. 2. Нажмите **Add server**. 3. Выберите **STDIO**, затем укажите команду запуска `npx -y mcp-yandex-merchants@latest`. 4. Нажмите **Save**, затем **Restart**. **Через командную строку:** ```bash codex mcp add yandex-merchants -- npx -y mcp-yandex-merchants@latest ``` Проверьте подключение: ```bash codex mcp list ``` Затем в чате Codex попросите: «Подключи Яндекс Товары». [Официальная инструкция Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
Claude Code
```bash claude mcp add --transport stdio --scope user yandex-merchants -- npx -y mcp-yandex-merchants@latest ``` Проверьте сервер командой: ```bash claude mcp list ``` Затем начните диалог с просьбы подключить Яндекс Товары. [Документация Claude Code](https://code.claude.com/docs/en/mcp)
Claude Desktop
Актуальный официальный путь — **Settings → Extensions**. Для пользовательского desktop extension откройте **Advanced settings → Extension Developer → Install Extension…**, выберите файл `.mcpb` и следуйте подсказкам. Этот репозиторий сейчас публикует npm-пакет со stdio и пока не содержит `.mcpb`. Поэтому используйте приведённый ниже JSON stdio-конфиг как fallback только в сборках Claude Desktop, где ещё поддерживается локальная конфигурация: ```json { "mcpServers": { "yandex-merchants": { "command": "npx", "args": ["-y", "mcp-yandex-merchants@latest"] } } } ``` В таких сборках сохраните его в `~/Library/Application Support/Claude/claude_desktop_config.json` на macOS или `%APPDATA%\Claude\claude_desktop_config.json` на Windows. После сохранения перезапустите Claude Desktop, откройте новый диалог и попросите подключить Яндекс Товары. [Документация Claude Desktop](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)
Cursor
Для всех проектов создайте `~/.cursor/mcp.json` (Windows: `%USERPROFILE%\.cursor\mcp.json`); только для текущего проекта — `.cursor/mcp.json`: ```json { "mcpServers": { "yandex-merchants": { "type": "stdio", "command": "npx", "args": ["-y", "mcp-yandex-merchants@latest"] } } } ``` В чате Cursor сервер появится среди доступных инструментов. Попросите подключить Яндекс Товары и пройдите вход через Яндекс. [Документация Cursor](https://cursor.com/docs/mcp)
VS Code
Откройте палитру команд и выполните **MCP: Open User Configuration**. Добавьте в `mcp.json`: ```json { "servers": { "yandex-merchants": { "type": "stdio", "command": "npx", "args": ["-y", "mcp-yandex-merchants@latest"] } } } ``` Проверьте запуск командой **MCP: List Servers**, затем откройте чат и попросите подключить Яндекс Товары. [Документация VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
> Это локальный MCP-сервер: приложение запускает `npx` на вашем компьютере. Веб-версии ChatGPT и Claude сами по себе не могут запустить такой процесс — используйте настольное приложение, CLI или редактор с поддержкой локальных MCP-серверов. ## Что можно поручить ### Проверить подключение и выбрать фид - **Проверить токен.** Убедиться, что сервер видит аккаунт, — `check_access`. - **Показать доступные фиды.** Получить `feedId` и адрес каждого фида — `list_feeds`. `feedId` понадобится для любого изменения. API не показывает состав фида, его статус и текущие значения товаров. ### Изменить цены и скидки - **Поменять цену одного товара** — `set_offer_price`. - **Обновить цены списком** до 2 000 товаров за один запрос — `update_offer_prices`. - **Задать скидку** с новой и зачёркнутой ценой — `set_offer_discount`. - **Добавить специальную цену** для Яндекс Пэй, СБП или карты Ozon — `set_offer_price`. Цены передаются только в рублях. Если в одном фиде несколько предложений с одинаковым id, API изменит только первое. ### Скрыть или вернуть товары - **Скрыть один товар** — `hide_offer`. - **Скрыть до 500 товаров** одной командой — `hide_offers`. - **Вернуть до 500 товаров в показ** — `show_offers`. Товар можно скрыть бессрочно или на срок до 720 часов. При бессрочном скрытии он останется невидимым до отдельной команды на возврат. ### Вызвать остальные методы API `raw_request` позволяет обратиться к методу партнёрского API, для которого нет отдельного готового действия. Он поддерживает `GET`, `POST` и `DELETE` и принимает данные в исходном формате API. > **`raw_request` может изменить реальные данные.** Если нужное действие уже есть среди готовых инструментов, безопаснее использовать его. Полные названия полей, форматы ответов и коды ошибок собраны в [справочнике инструментов](./docs/TOOLS.md). ## Как это работает Сервер не создаёт, не удаляет и не загружает фиды. Он берёт `feedId` уже существующего YML-фида и отправляет в Яндекс Товары точечные изменения для указанных товаров. Это удобно, когда нужно быстро: - исправить одну или несколько цен; - поставить скидку; - скрыть закончившийся товар; - вернуть товар в показ. Сам YML-фид по-прежнему управляется через кабинет Яндекс Товаров или Вебмастер. Содержимое фида сервер прочитать не может, поэтому id товаров и журнал изменений нужно хранить на своей стороне. ## Что может изменить данные | Действие | Что происходит | Меняет данные | |---|---|---:| | `check_access`, `list_feeds` | Проверяет токен и показывает id и адреса фидов | Нет | | `set_offer_price`, `set_offer_discount` | Меняет цену одного товара | **Да** | | `update_offer_prices` | Меняет цены у 1–2 000 товаров | **Да** | | `hide_offer`, `hide_offers` | Скрывает один или несколько товаров | **Да** | | `show_offers` | Возвращает скрытые товары в показ | **Да** | | `raw_request` | Выполняет выбранный вызов API | Зависит от метода | Сервер снижает риск ошибок следующим образом: - проверяет обязательные поля, размеры списков, длину id, положительные цены и диапазон скидки до отправки запроса; - проверяет `status` в теле ответа, потому что HTTP 200 ещё не означает успешную запись; - не повторяет запись автоматически после ошибки сервера или обрыва связи; - не позволяет `raw_request` отправить OAuth-токен на посторонний адрес; - сообщает AI-приложению, какие действия читают данные, а какие их изменяют. > **Подтверждение перед записью зависит от AI-приложения.** Если хотите сначала проверить значения, попросите ассистента подготовить изменение, показать `feedId`, id товара и новые значения, а выполнить его — только после следующей команды. ## Подключение и настройка Для обычного использования токен заранее не нужен: 1. В чате попросите подключить Яндекс Товары. 2. Откройте ссылку на Яндекс OAuth **строго под тем логином Яндекса, под которым загружен YML-фид** — токен другого логина не увидит ни одного фида. 3. Подтвердите доступ и пришлите код ассистенту. Код одноразовый и действует 10 минут. Сервер использует PKCE: код из чата сам по себе нельзя обменять на токен — это может сделать только ваш запущенный сервер. Он запрашивает единственное право — `products:partner-api` («API поиска по товарам»). Полученный токен хранится локально в `~/.config/mcp-yandex-merchants/credentials.json` с правами только для владельца и продлевается автоматически. Перезапускать AI-приложение после входа не нужно. Проверить состояние — попросите «покажи статус подключения», отключить — «отключи Яндекс Товары». Выданный доступ отзывается в [Яндекс ID](https://id.yandex.ru/security). Для CI и нестандартных установок доступна настройка через переменные окружения: | Переменная | Назначение | |---|---| | `YANDEX_MERCHANTS_OAUTH_TOKEN` | Готовый OAuth-токен с доступом `products:partner-api` — для CI и установок без диалога. Имеет приоритет над входом из диалога; сервер такой токен не обновляет и не удаляет. | | `YANDEX_MERCHANTS_OAUTH_CLIENT_ID` | ClientID собственного OAuth-приложения для входа из диалога вместо приложения A1 по умолчанию. | | `YANDEX_MERCHANTS_BASE_URL` | Корневой адрес API; по умолчанию `https://yandex.ru/products/api/ext/partner`. | | `YANDEX_MERCHANTS_TIMEOUT_MS` | Таймаут одного запроса; по умолчанию 60 000 мс. | | `YANDEX_MERCHANTS_MAX_RETRIES` | Число повторов при `429`; по умолчанию 3. При `5xx` и сетевых ошибках повторяются только запросы на чтение. | Если используете собственное OAuth-приложение, зарегистрируйте его на [oauth.yandex.ru/client/new](https://oauth.yandex.ru/client/new) (платформа «Веб-сервисы», Redirect URI `https://oauth.yandex.ru/verification_code`) и добавьте доступ `products:partner-api` — «API поиска по товарам». Готовый токен для `YANDEX_MERCHANTS_OAUTH_TOKEN` выдаёт страница `https://oauth.yandex.ru/authorize?response_type=token&client_id=`, открытая под логином, который загрузил YML-фид. Храните токен как пароль: не добавляйте конфигурацию с реальным токеном в Git и не отправляйте её посторонним. ## Данные и телеметрия Сервер запускается на вашем компьютере и напрямую обращается к `https://yandex.ru/products/api/ext/partner`. OAuth-токен добавляется только к запросам этого API: даже `raw_request` принимает относительный путь и не может отправить токен на другой сайт. При входе из диалога сервер дополнительно обращается к `oauth.yandex.ru` — только чтобы обменять код подтверждения на токен и продлевать его. По умолчанию сервер отправляет на `usage.gistrec.cloud` анонимную техническую телеметрию: случайный идентификатор установки, имя события или инструмента, версию пакета, версию Node.js, ОС и сведения о подключившемся AI-клиенте. В неё не попадают OAuth-токен, данные аккаунта, id фидов и товаров, цены, аргументы инструментов и тексты запросов. Отправка выполняется в фоне и не влияет на работу сервера. Чтобы отключить телеметрию для MCP-серверов A1, задайте переменную окружения: ```bash ASKADS_TELEMETRY=0 ``` ## Ограничения - **Нельзя прочитать текущее состояние товаров.** API не возвращает текущие цены, список скрытых товаров, содержимое или статус фида. Храните журнал изменений на своей стороне. - **Нельзя управлять самими фидами.** Создать, удалить или перезагрузить YML-фид можно только в кабинете или Вебмастере. - **Только рубли.** Другие валюты API не принимает. - **Id товара — до 50 символов.** Более длинный идентификатор API не примет. - **До 2 000 цен за запрос.** Для скрытия и возврата — до 500 товаров за запрос. - **До 50 000 операций в минуту.** Отдельно считаются изменения цен и общая сумма скрытий с возвратами. - **Нет автоматического отката.** После обрыва связи результат записи может остаться неизвестным, а прочитать состояние через этот API нельзя. Не повторяйте такую операцию автоматически. - **Нет постоянного наблюдения.** Сервер работает только тогда, когда AI-приложение вызывает его. Если приложение поддерживает задания по расписанию, можно попросить его периодически проверять доступ или выполнять заранее заданный сценарий. ## Техническая документация - [Каталог MCP-возможностей](./docs/capabilities/index.md) — страницы по пользовательским задачам для каждого инструмента. - [Все инструменты](./docs/TOOLS.md) — параметры, ответы, коды ошибок и ограничения. - [Документация по разработке](./docs/DEVELOPMENT.md) — локальный запуск, проверки и сборка. - [Публикация](./docs/PUBLISHING.md) — выпуск npm-пакета и публикация в каталогах MCP. - [Пакет в npm](https://www.npmjs.com/package/mcp-yandex-merchants). - [API Яндекс Товаров](https://yandex.ru/dev/products/doc/ru/). ## Поддержка Нашли ошибку или не хватает сценария? [Создайте issue](https://github.com/A1-x-Tech/mcp-yandex-merchants/issues) или напишите в [Telegram](https://t.me/a1_mcp).