Yandex Market Seller

Official

by dontsovcmc · Python

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

Manage Yandex Market orders, offers, prices, stocks, and analytics.

README.md16 KBView on GitHub

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-сервер
CLI-утилита
Pydantic-модели
- Установка (библиотеки)
- Использование в своих программах
Переменные окружения
Разработка
Лицензия

Архитектура

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

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

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

code

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-ключ

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

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

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

bash

# После установки и настройки токена:
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

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:

code

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

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

Переменная	Обязательная	По умолчанию	Описание
`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

Install

Configuration

Environment variables

YM_TOKENrequiredsecret

YM_CAMPAIGN_ID

YM_BUSINESS_ID

YM_AUTH_TYPE

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "yandex-market-seller": {
      "command": "uvx",
      "args": [
        "mcp-server-yandex-market-seller"
      ],
      "env": {
        "YM_TOKEN": "<YOUR_YM_TOKEN>",
        "YM_CAMPAIGN_ID": "<YOUR_YM_CAMPAIGN_ID>",
        "YM_BUSINESS_ID": "<YOUR_YM_BUSINESS_ID>",
        "YM_AUTH_TYPE": "<YOUR_YM_AUTH_TYPE>"
      }
    }
  }
}

mcp-server-yandex-market-seller

Оглавление

Архитектура

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

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

MCP-сервер

Установка

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

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

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

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

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

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

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

Примеры (MCP)

CLI-утилита

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

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

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

Pydantic-модели

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

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

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

Разработка

Лицензия

Install

Configuration