# Yandex Merchants MCP

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/A1-x-Tech/mcp-yandex-merchants  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/yandex-merchants-mcp

## Description
MCP server for the Yandex Merchants partner API: feeds, offer prices, discounts, hide/unhide.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "yandex-merchants-mcp": {
    "command": "npx",
    "args": ["-y","yandex-merchants-mcp"]
  }
}
```

## Documentation & README

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

[![npm](https://img.shields.io/npm/v/mcp-yandex-merchants)](https://www.npmjs.com/package/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)

<img src="./assets/a1-logo.svg" alt="A1" width="22">&nbsp;**Яндекс Товары MCP** — MCP-сервер, с которым Claude, Cursor, Codex и другие AI-клиенты обновляют цены, скидки и видимость офферов в [Яндекс Товарах](https://merchants.yandex.ru) по обычной команде. Он работает поверх уже загруженного 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`. Все остальные специализированные инструменты изменяют данные в Яндекс Товарах.

[Подключить сервер](#быстрый-старт) · [Посмотреть сценарии](#что-можно-поручить) · [Открыть справочник инструментов](docs/TOOLS.md)

---

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

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

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

---

## Содержание

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

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

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

1. [Получите OAuth-токен](#получение-доступа-к-api) под тем же логином, который загрузил фид.

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

   ```bash
   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-клиенты»](#установка-в-другие-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` помечен как разрушительный инструмент.** Он способен выполнять произвольную запись. Используйте специализированный инструмент, если он уже есть.

Полные входные схемы, коды ошибок и форматы ответов собраны в [справочнике инструментов](docs/TOOLS.md).

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

Партнёрский 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>

```bash
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>

```bash
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\`.

```json
{
  "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` проекта:

```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`:

```json
{
  "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](https://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, добавьте:

```text
ASKADS_TELEMETRY=0
```

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

## Ограничения

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

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

- [Все инструменты](docs/TOOLS.md) — входные данные, ответы, коды ошибок и ограничения.
- [Разработка](docs/DEVELOPMENT.md) — локальный запуск, тесты, сборка и read-only smoke-проверка.
- [Публикация](docs/PUBLISHING.md) — выпуск npm-пакета и листинг в каталогах MCP.
- [npm-пакет](https://www.npmjs.com/package/mcp-yandex-merchants) — опубликованная версия `mcp-yandex-merchants`.
- [API Яндекс Товаров](https://yandex.ru/dev/products/doc/ru/) — официальная документация.

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

```bash
npm install
npm run typecheck
npm test
```

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

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

Нашли ошибку или не хватает сценария? [Создайте issue](https://github.com/A1-x-Tech/mcp-yandex-merchants/issues) или напишите в Telegram: [@gistrec](https://t.me/gistrec).

## Лицензия

MIT — см. [LICENSE](LICENSE).