mcp-server-yandex-market-seller

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

mcp-server-yandex-market-seller


MCP-сервер, CLI-утилита и библиотека Pydantic-моделей для Yandex Market Partner API.

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

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

Оглавление

• Архитектура
• Доступные действия (131)
• MCP-сервер
• Установка
• Подключение к Claude Code
• Подключение к Claude Desktop
• Подключение через --mcp-config
• Примеры (MCP)
• CLI-утилита
• Установка (CLI)
• Использование (CLI)
• Примеры команд
• 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 | 6 | Кампании и настройки бизнеса | | orders | 28 | Заказы: список, детали, статусы, этикетки, документы | | returns | 9 | Возвраты: решения, заявления | | shipments | 14 | Отгрузки: акты, накладные, паллеты | | warehouses | 4 | Склады бизнеса и Яндекс Маркета | | offers | 8 | Товары: offer-mappings, скрытые, штрихкоды | | offer_cards | 3 | Карточки товаров и рекомендации | | prices | 6 | Цены и карантин цен | | stocks | 2 | Остатки товаров | | delivery | 4 | Службы доставки и точки логистики | | feedbacks | 5 | Отзывы покупателей и комментарии | | questions | 3 | Вопросы покупателей | | quality | 2 | Рейтинг качества продавца | | promos | 4 | Акции и промо | | bids | 5 | Ставки (бизнес и кампания) | | outlets | 6 | Точки продаж и лицензии | | geo | 4 | Регионы и страны | | categories | 3 | Категории Маркета и параметры | | tariffs | 1 | Расчёт тарифов и комиссий | | chats | 5 | Чаты с покупателями | | reports | 3 | Асинхронные отчёты | | stats | 2 | Статистика заказов и SKU | | supply | 3 | Заявки на поставку | | operations | 1 | Асинхронные операции |

---

MCP-сервер

Установка

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

1. Откройте личный кабинет Яндекс Маркета
2. Перейдите в Настройки → API-ключи
3. Создайте новый ключ с нужными правами
4. Скопируйте API-ключ

Альтернативно можно использовать OAuth-токен.

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

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

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

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

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

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

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

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

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)

pip install mcp-server-yandex-market-seller

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# Кампании
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.

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

pip install mcp-server-yandex-market-seller

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

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

---

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

| Переменная | Обязательная | По умолчанию | Описание | |-----------|:------------:|:------------:|----------| | 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 как параметр — это позволяет работать с несколькими магазинами в одной сессии.

Разработка

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

Лицензия

MIT