mcp-yandex-merchants

# Яндекс Товары MCP

[![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)
[![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)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)

**Яндекс Товары 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 → Plugins → MCP servers**.
2. Нажмите **Add server**.
3. Добавьте команду запуска `npx -y mcp-yandex-merchants@latest`.

**Через командную строку:**

```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 → Developer → Edit Config** и добавьте сервер в `claude_desktop_config.json`:

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

Если кнопки **Edit Config** нет, откройте файл напрямую:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

После сохранения перезапустите Claude Desktop, откройте новый диалог и попросите подключить Яндекс Товары.

[Документация Claude Desktop](https://claude.com/docs/connectors/building/mcp-apps/getting-started)

</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 **строго под тем логином Яндекса, под к