Yandex Merchants MCP
MCP server for the Yandex Merchants partner API: feeds, offer prices, discounts, hide/unhide.
Open source Open in the app JSON README (API)
About
MCP server for the Yandex Merchants partner API: feeds, offer prices, discounts, hide/unhide.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- a1-x-tech
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.1.1
- Last push
- 2026-08-30T13:36:12Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:01:38
- Updated
- 2026-08-29 03:01:38
- Origin id
io.github.A1-x-Tech/mcp-yandex-merchants
README
# <img src="./assets/a1-logo.svg" alt="A1" width="40"> Яндекс Товары MCP
[](https://www.npmjs.com/package/mcp-yandex-merchants)
[](https://github.com/A1-x-Tech/mcp-yandex-merchants/actions/workflows/ci.yml)
[](https://glama.ai/mcp/servers/A1-x-Tech/mcp-yandex-merchants)
[](./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. Проверьте подключение: «Проверь подключение к Яндекс Товарам и покажи доступные фиды». Если сервер вернул список фидов, можно переходить к ценам и видимости товаров.
<details open>
<summary><strong>Codex</strong></summary>
<br>
**Через интерфейс приложения:**
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)
</details>
<details>
<summary><strong>Claude Code</strong></summary>
<br>
```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)
</details>
<details>
<summary><strong>Claude Desktop</strong></summary>
<br>
Актуальный официальный путь — **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)
</details>
<details>
<summary><strong>Cursor</strong></summary>
<br>
Для всех проектов создайте `~/.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)
</details>
<details>
<summary><strong>VS Code</strong></summary>
<br>
Откройте палитру команд и выполните **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)
</details>
> Это локальный 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=<ClientID>`, открытая под логином, который загрузил 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).