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 — если не установлен:

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

Для удаления:

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:

{
  "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):

{
  "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-строки:

claude --mcp-config '{"yandex-market-seller":{"command":"bash","args":["-c","source ~/.env.mcp && exec uvx mcp-server-yandex-market-seller"]}}'

Из файла:

claude --mcp-config ~/mcp-servers.json

Пример ~/mcp-servers.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