# yandex-market-seller [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/dontsovcmc/mcp-server-yandex-market-seller  
**GitHub Stars:** 1  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/yandex-market-seller

## Description
MCP server for Yandex Market Partner API — orders, offers, prices, stocks, analytics

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "yandex-market-seller": {
    "command": "uvx",
    "args": ["mcp-server-yandex-market-seller"]
  }
}
```

## Documentation & README

<!-- mcp-name: io.github.dontsovcmc/yandex-market-seller -->

# mcp-server-yandex-market-seller

[![Version](https://img.shields.io/badge/version-0.6.0-blue)](https://github.com/dontsovcmc/mcp-server-yandex-market-seller)

MCP-сервер, CLI-утилита и библиотека Pydantic-моделей для [Yandex Market Partner API](https://yandex.ru/dev/market/partner-api/doc/).

- **MCP-сервер** — интеграция с Claude Code, Claude Desktop и другими MCP-клиентами
- **CLI-утилита** — работа с API из терминала, скрипты и автоматизация
- **Pydantic-модели** — типизированные модели API для использования в своих Python-программах

Все данные остаются на вашем компьютере — токен никуда не передаётся.

## Оглавление

- [Архитектура](#архитектура)
- [Доступные действия (131)](#доступные-действия-131)
- [MCP-сервер](#mcp-сервер)
  - [Установка](#установка)
  - [Подключение к Claude Code](#подключение-к-claude-code)
  - [Подключение к Claude Desktop](#подключение-к-claude-desktop)
  - [Подключение через --mcp-config](#подключение-через---mcp-config)
  - [Примеры (MCP)](#примеры-mcp)
- [CLI-утилита](#cli-утилита)
  - [Установка (CLI)](#установка-cli)
  - [Использование (CLI)](#использование-cli)
  - [Примеры команд](#примеры-команд)
- [Pydantic-модели](#pydantic-модели)
  - [Установка (библиотеки)](#установка-библиотеки)
  - [Использование в своих программах](#использование-в-своих-программах)
- [Переменные окружения](#переменные-окружения)
- [Разработка](#разработка)
- [Лицензия](#лицензия)

## Архитектура

Сервер использует паттерн **search + execute** — вместо 131 отдельного инструмента предоставляет 3:

| Инструмент | Описание |
|------------|----------|
| `ym_search` | Поиск действий по описанию на естественном языке |
| `ym_execute` | Выполнение действия по ID |
| `ym_execute_file` | Выполнение действия со скачиванием файла |

### Как это работает

```
LLM: ym_search("скачать этикетки заказа")
→ [{"id": "order_labels", "params_schema": {"order_id": "int"}, ...}]

LLM: ym_execute_file("order_labels", "/tmp/labels.pdf", '{"order_id": 12345}')
→ {"path": "/tmp/labels.pdf", "size": 48392}
```

---

## Доступные действия (131)

| Домен | Кол-во | Описание |
|-------|--------|----------|
| [`campaigns`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/campaigns.md) | 6 | Кампании и настройки бизнеса |
| [`orders`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/orders.md) | 28 | Заказы: список, детали, статусы, этикетки, документы |
| [`returns`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/returns.md) | 9 | Возвраты: решения, заявления |
| [`shipments`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/shipments.md) | 14 | Отгрузки: акты, накладные, паллеты |
| [`warehouses`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/warehouses.md) | 4 | Склады бизнеса и Яндекс Маркета |
| [`offers`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/offers.md) | 8 | Товары: offer-mappings, скрытые, штрихкоды |
| [`offer_cards`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/offer_cards.md) | 3 | Карточки товаров и рекомендации |
| [`prices`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/prices.md) | 6 | Цены и карантин цен |
| [`stocks`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/stocks.md) | 2 | Остатки товаров |
| [`delivery`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/delivery.md) | 4 | Службы доставки и точки логистики |
| [`feedbacks`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/feedbacks.md) | 5 | Отзывы покупателей и комментарии |
| [`questions`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/questions.md) | 3 | Вопросы покупателей |
| [`quality`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/quality.md) | 2 | Рейтинг качества продавца |
| [`promos`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/promos.md) | 4 | Акции и промо |
| [`bids`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/bids.md) | 5 | Ставки (бизнес и кампания) |
| [`outlets`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/outlets.md) | 6 | Точки продаж и лицензии |
| [`geo`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/geo.md) | 4 | Регионы и страны |
| [`categories`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/categories.md) | 3 | Категории Маркета и параметры |
| [`tariffs`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/tariffs.md) | 1 | Расчёт тарифов и комиссий |
| [`chats`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/chats.md) | 5 | Чаты с покупателями |
| [`reports`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/reports.md) | 3 | Асинхронные отчёты |
| [`stats`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/stats.md) | 2 | Статистика заказов и SKU |
| [`supply`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/supply.md) | 3 | Заявки на поставку |
| [`operations`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/docs/operations.md) | 1 | Асинхронные операции |

---

## MCP-сервер

### Установка

#### Шаг 1. Получить API-ключ

1. Откройте [личный кабинет Яндекс Маркета](https://partner.market.yandex.ru)
2. Перейдите в **Настройки** → **API-ключи**
3. Создайте новый ключ с нужными правами
4. Скопируйте API-ключ

Альтернативно можно использовать [OAuth-токен](https://oauth.yandex.ru/).

#### Шаг 2. Узнать ID кампании и бизнеса

```bash
# После установки и настройки токена:
mcp-server-yandex-market-seller campaigns
```

Запишите `campaignId` и `businessId` из вывода.

#### Шаг 3. Подключить MCP-сервер

### Подключение к Claude Code

**Способ 1: через uvx** (не требует установки пакета)

> Требуется [uv](https://docs.astral.sh/uv/) — если не установлен:
> ```bash
> curl -LsSf https://astral.sh/uv/install.sh | sh
> ```

```bash
claude mcp add yandex-market-seller \
  -e YM_TOKEN=ваш_api_ключ \
  -e YM_CAMPAIGN_ID=12345 \
  -e YM_BUSINESS_ID=67890 \
  -- uvx mcp-server-yandex-market-seller
```

**Способ 2: через pip**

```bash
pip install mcp-server-yandex-market-seller

claude mcp add yandex-market-seller \
  -e YM_TOKEN=ваш_api_ключ \
  -e YM_CAMPAIGN_ID=12345 \
  -e YM_BUSINESS_ID=67890 \
  -- python -m mcp_server_yandex_market_seller
```

Для удаления:
```bash
claude mcp remove yandex-market-seller
```

### Подключение к Claude Desktop

Добавьте в конфигурационный файл:

| Клиент | ОС | Путь к файлу |
|--------|----|-------------|
| Claude Code | все | `~/.claude/settings.json` (секция `mcpServers`) |
| Claude Desktop | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop | Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Claude Desktop | Linux | `~/.config/Claude/claude_desktop_config.json` |

**Через uvx:**
```json
{
  "mcpServers": {
    "yandex-market-seller": {
      "command": "uvx",
      "args": ["mcp-server-yandex-market-seller"],
      "env": {
        "YM_TOKEN": "ваш_api_ключ",
        "YM_CAMPAIGN_ID": "12345",
        "YM_BUSINESS_ID": "67890"
      }
    }
  }
}
```

**Через pip** (после `pip install mcp-server-yandex-market-seller`):
```json
{
  "mcpServers": {
    "yandex-market-seller": {
      "command": "python",
      "args": ["-m", "mcp_server_yandex_market_seller"],
      "env": {
        "YM_TOKEN": "ваш_api_ключ",
        "YM_CAMPAIGN_ID": "12345",
        "YM_BUSINESS_ID": "67890"
      }
    }
  }
}
```

### Подключение через --mcp-config

Подключает сервер только на время одной сессии Claude, не сохраняя в настройки. Токен хранится в отдельном `.env.mcp` файле, а не в конфиге Claude.

Из JSON-строки:
```bash
claude --mcp-config '{"yandex-market-seller":{"command":"bash","args":["-c","source ~/.env.mcp && exec uvx mcp-server-yandex-market-seller"]}}'
```

Из файла:
```bash
claude --mcp-config ~/mcp-servers.json
```

Пример `~/mcp-servers.json`:
```json
{
  "yandex-market-seller": {
    "command": "bash",
    "args": ["-c", "source ~/.env.mcp && exec uvx mcp-server-yandex-market-seller"]
  }
}
```

Пример `~/.env.mcp`:
```
YM_TOKEN=ваш_api_ключ
YM_CAMPAIGN_ID=12345
YM_BUSINESS_ID=67890
```

#### Шаг 4. Проверить

Попросите Claude: *«покажи мои заказы на Маркете»* — он вызовет `ym_search`, затем `ym_execute`.

### Примеры (MCP)

- «покажи мои заказы» → `ym_search("list orders")` → `ym_execute("orders")`
- «отправь заказ 12345» → `ym_execute("order_status", '{"order_id": 12345, "status": "DELIVERY"}')`
- «скачай этикетки для заказа 12345» → `ym_execute_file("order_labels", "/tmp/labels.pdf", '{"order_id": 12345}')`
- «какие цены на SKU1?» → `ym_execute("prices", '{"offer_ids": ["SKU1"]}')`
- «обнови остатки SKU1 до 50 шт.» → `ym_execute("stocks_update", '{"skus": [{"shopSku": "SKU1", "warehouseId": 111, "items": [{"count": 50, "type": "FIT"}]}]}')`
- «покажи возвраты» → `ym_execute("returns")`
- «покажи отзывы» → `ym_execute("feedbacks")`
- «сгенерируй отчёт united-netting» → `ym_execute("report_generate", '{"report_type": "united-netting"}')`

---

## CLI-утилита

### Установка (CLI)

```bash
pip install mcp-server-yandex-market-seller
```

Переменные окружения `YM_TOKEN`, `YM_CAMPAIGN_ID` и `YM_BUSINESS_ID` должны быть установлены:

```bash
export YM_TOKEN=ваш_api_ключ
export YM_CAMPAIGN_ID=12345
export YM_BUSINESS_ID=67890
```

Или через файл:

```bash
mcp-server-yandex-market-seller --env /path/to/.env <command>
```

Формат файла — `KEY=VALUE`, по одной переменной на строку, `#`-комментарии.

### Использование (CLI)

Без аргументов запускается MCP-сервер, с командой — CLI. Все команды выводят JSON.

Переменная окружения `YM_TOKEN` должна быть установлена:

```bash
export YM_TOKEN=ваш_api_ключ
export YM_CAMPAIGN_ID=12345
export YM_BUSINESS_ID=67890
```

Или через файл:

```bash
mcp-server-yandex-market-seller --env /path/to/.env <command>
```

Формат файла — `KEY=VALUE`, по одной переменной на строку, `#`-комментарии.

```bash
# Версия
mcp-server-yandex-market-seller --version

# Справка
mcp-server-yandex-market-seller --help
mcp-server-yandex-market-seller <command> --help
```

### Примеры команд

```bash
# Кампании
mcp-server-yandex-market-seller campaigns
mcp-server-yandex-market-seller campaign
mcp-server-yandex-market-seller campaign-settings
mcp-server-yandex-market-seller business-settings

# Заказы
mcp-server-yandex-market-seller orders
mcp-server-yandex-market-seller orders --status PROCESSING
mcp-server-yandex-market-seller order 12345
mcp-server-yandex-market-seller order-status 12345 DELIVERY
mcp-server-yandex-market-seller order-labels 12345 labels.pdf
mcp-server-yandex-market-seller order-items 12345
mcp-server-yandex-market-seller order-buyer 12345
mcp-server-yandex-market-seller order-tracking 12345
mcp-server-yandex-market-seller order-documents 12345
mcp-server-yandex-market-seller order-stats --date-from 2026-04-01

# Возвраты
mcp-server-yandex-market-seller returns
mcp-server-yandex-market-seller return 12345 67890

# Отгрузки
mcp-server-yandex-market-seller shipments
mcp-server-yandex-market-seller shipment 12345
mcp-server-yandex-market-seller shipment-orders 12345
mcp-server-yandex-market-seller shipment-act 12345 act.pdf

# Товары
mcp-server-yandex-market-seller offers
mcp-server-yandex-market-seller offers --offer-ids SKU1,SKU2
mcp-server-yandex-market-seller offer-cards
mcp-server-yandex-market-seller campaign-offers
mcp-server-yandex-market-seller hidden-offers

# Цены и остатки
mcp-server-yandex-market-seller prices
mcp-server-yandex-market-seller prices --offer-ids SKU1
mcp-server-yandex-market-seller price-quarantine
mcp-server-yandex-market-seller stocks

# Акции и ставки
mcp-server-yandex-market-seller promos
mcp-server-yandex-market-seller promo-offers cf_137460
mcp-server-yandex-market-seller bids
mcp-server-yandex-market-seller bid-recommendations

# Склады и доставка
mcp-server-yandex-market-seller warehouses
mcp-server-yandex-market-seller all-warehouses
mcp-server-yandex-market-seller logistics-points
mcp-server-yandex-market-seller delivery-services

# Покупатели
mcp-server-yandex-market-seller feedbacks
mcp-server-yandex-market-seller feedback-comments 12345
mcp-server-yandex-market-seller questions
mcp-server-yandex-market-seller chats
mcp-server-yandex-market-seller chat-history 12345
mcp-server-yandex-market-seller chat-send 12345 "Ваш заказ отправлен"

# Точки продаж
mcp-server-yandex-market-seller outlets
mcp-server-yandex-market-seller outlet 12345

# Аналитика
mcp-server-yandex-market-seller quality
mcp-server-yandex-market-seller quality-details
mcp-server-yandex-market-seller sku-stats
mcp-server-yandex-market-seller report-status abc123

# Справочники
mcp-server-yandex-market-seller regions Москва
mcp-server-yandex-market-seller region 213
mcp-server-yandex-market-seller countries
mcp-server-yandex-market-seller categories
mcp-server-yandex-market-seller category-params 12345

# Поставки
mcp-server-yandex-market-seller supply-requests
mcp-server-yandex-market-seller operations
```

---

## Pydantic-модели

Пакет содержит типизированные Pydantic-модели параметров API. Модели можно использовать в своих Python-программах для валидации данных и автодополнения в IDE.

### Установка (библиотеки)

```bash
pip install mcp-server-yandex-market-seller
```

### Использование в своих программах

```python
from mcp_server_yandex_market_seller.models import OrdersListParams

# Валидация данных
params = OrdersListParams.model_validate({
    "status": "PROCESSING",
    "page": 1,
    "page_size": 50,
})
print(params.model_dump_json())

# Создание объекта
params = OrdersListParams(status="DELIVERY", page_size=100)
print(params.status)  # type-safe доступ к полям
```

Все модели используют `extra="allow"` для forward compatibility — неизвестные поля API не вызывают ошибок.

Полный список моделей: [`models.py`](https://github.com/dontsovcmc/mcp-server-yandex-market-seller/blob/HEAD/src/mcp_server_yandex_market_seller/models.py)

---

## Переменные окружения

| Переменная | Обязательная | По умолчанию | Описание |
|-----------|:------------:|:------------:|----------|
| `YM_TOKEN` | да | — | API-ключ или OAuth-токен |
| `YM_AUTH_TYPE` | нет | `api-key` | `api-key` или `oauth` |
| `YM_CAMPAIGN_ID` | да | — | ID кампании (магазина) |
| `YM_BUSINESS_ID` | да | — | ID бизнеса |
| `YM_TIMEOUT` | нет | `30` | Таймаут HTTP-запросов (секунды) |
| `YM_FILE_TIMEOUT` | нет | `60` | Таймаут файловых операций (секунды) |

Каждый инструмент также принимает `campaign_id`/`business_id` как параметр — это позволяет работать с несколькими магазинами в одной сессии.

## Разработка

```bash
pip install -e ".[test]"
ruff check src/ tests/
pytest tests/ -v
```

## Лицензия

MIT