# 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 ``` Формат файла — `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 ``` Формат файла — `KEY=VALUE`, по одной переменной на строку, `#`-комментарии. ```bash # Версия mcp-server-yandex-market-seller --version # Справка mcp-server-yandex-market-seller --help mcp-server-yandex-market-seller --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