io.github.dontsovcmc/yandex-market-seller
MCP server for Yandex Market Partner API — orders, offers, prices, stocks, analytics
Open source Open in the app JSON README (API)
About
MCP server for Yandex Market Partner API — orders, offers, prices, stocks, analytics
Details
- Kind
- MCP servers
- Topic
- Marketing & analytics
- Publisher
- dontsovcmc
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.6.0
- Stars
- 1
- Open pull requests
- 1
- Last push
- 2026-05-10T13:31:58Z
- Repository state
- ativo
- Language
- Python
- Added
- 2026-08-29 03:02:43
- Updated
- 2026-08-29 03:02:43
- Origin id
io.github.dontsovcmc/yandex-market-seller
README
<!-- mcp-name: io.github.dontsovcmc/yandex-market-seller -->
# mcp-server-yandex-market-seller
[](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`](docs/campaigns.md) | 6 | Кампании и настройки бизнеса |
| [`orders`](docs/orders.md) | 28 | Заказы: список, детали, статусы, этикетки, документы |
| [`returns`](docs/returns.md) | 9 | Возвраты: решения, заявления |
| [`shipments`](docs/shipments.md) | 14 | Отгрузки: акты, накладные, паллеты |
| [`warehouses`](docs/warehouses.md) | 4 | Склады бизнеса и Яндекс Маркета |
| [`offers`](docs/offers.md) | 8 | Товары: offer-mappings, скрытые, штрихкоды |
| [`offer_cards`](docs/offer_cards.md) | 3 | Карточки товаров и рекомендации |
| [`prices`](docs/prices.md) | 6 | Цены и карантин цен |
| [`stocks`](docs/stocks.md) | 2 | Остатки товаров |
| [`delivery`](docs/delivery.md) | 4 | Службы доставки и точки логистики |
| [`feedbacks`](docs/feedbacks.md) | 5 | Отзывы покупателей и комментарии |
| [`questions`](docs/questions.md) | 3 | Вопросы покупателей |
| [`quality`](docs/quality.md) | 2 | Рейтинг качества продавца |
| [`promos`](docs/promos.md) | 4 | Акции и промо |
| [`bids`](docs/bids.md) | 5 | Ставки (бизнес и кампания) |
| [`outlets`](docs/outlets.md) | 6 | Точки продаж и лицензии |
| [`geo`](docs/geo.md) | 4 | Регионы и страны |
| [`categories`](docs/categories.md) | 3 | Категории Маркета и параметры |
| [`tariffs`](docs/tariffs.md) | 1 | Расчёт тарифов и комиссий |
| [`chats`](docs/chats.md) | 5 | Чаты с покупателями |
| [`reports`](docs/reports.md) | 3 | Асинхронные отчёты |
| [`stats`](docs/stats.md) | 2 | Статистика заказов и SKU |
| [`supply`](docs/supply.md) | 3 | Заявки на поставку |
| [`operations`](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`](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