# Yandex Delivery MCP **Category:** 💻 Developer Tools **Repository:** https://github.com/A1-x-Tech/mcp-yandex-dostavka **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/yandex-delivery-mcp ## Description MCP server for the Yandex Delivery B2B API: express claims, tracking, NDD/pickup-point orders. ## Claude Desktop Quick Installation Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "yandex-delivery-mcp": { "command": "npx", "args": ["-y","yandex-delivery-mcp"] } } ``` ## Documentation & README # Скажите, что и куда доставить, — AI-ассистент рассчитает, оформит и даст трекинг [![npm](https://img.shields.io/npm/v/mcp-yandex-dostavka)](https://www.npmjs.com/package/mcp-yandex-dostavka) [![CI](https://github.com/A1-x-Tech/mcp-yandex-dostavka/actions/workflows/ci.yml/badge.svg)](https://github.com/A1-x-Tech/mcp-yandex-dostavka/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) A1 **Яндекс Доставка MCP** — MCP-сервер, с которым Claude, Cursor, Codex и другие AI-клиенты рассчитывают, оформляют и отслеживают B2B-доставки по обычной команде. В отличие от ручной работы с API, он уже знает оба контура Яндекс Доставки, их схемы и границы между расчётом и реальным заказом. - **Оба контура API.** Экспресс-доставка день в день и Платформа для доставки в другой день, ПВЗ и постаматов. - **16 готовых инструментов.** 9 для Экспресса, 6 для Платформы и универсальный `raw_request` для остальных методов API. - **Результат обычными словами.** Ассистент получает строгие схемы входных данных, русские описания и ответы Яндекс Доставки без промежуточного формата. - **Защита от случайных повторов.** Сервер создаёт `request_id` для экспресс-заявок, повторяет безопасные запросы при временных ошибках и не ретраит неидемпотентные записи после 5xx или обрыва связи. - **Явные уровни риска.** Каждый инструмент помечен как чтение, запись или разрушительное действие; AI-клиент может использовать эти метки для предупреждений и подтверждений. - **Без глобальной установки.** Пакет запускается через `npx` на Node.js 20+ и подключается к клиенту по `stdio`. **Кому подходит:** командам, которые уже подключены к B2B API Яндекс Доставки и хотят управлять отдельными отправлениями из привычного AI-приложения. Это не приложение для частных отправителей и не замена договору или токену Яндекс Доставки. Когда бизнес уже работает с Яндекс Доставкой, даже одна отправка через API превращается в цепочку действий: выбрать нужный контур, собрать JSON, не перепутать единицы измерения, дождаться оценки, подтвердить заявку и найти ссылку для получателя. С MCP-сервером вы описываете нужный результат обычными словами, а ассистент вызывает подходящие методы — без собственной интеграции и ручной сборки HTTP-запросов. **Узнать цену — без создания заявки** > **Вы:** Посчитай доставку коробки 2 кг из офиса на Льва Толстого, 16 клиенту на Тверскую, 7. Ничего не заказывай. > > **Ассистент:** Запрошу только предварительный расчёт и верну цену, расстояние и ETA. Заявка создана не будет. **Подготовить отправку, но пока не вызывать курьера** > **Вы:** Создай экспресс-заявку по этим данным, дождись оценки, но не подтверждай её. > > **Ассистент:** Заявка создана и оценена. Покажу итоговую цену и статус; поиск курьера не запущен. **Вы управляете границей между расчётом и реальным заказом.** Расчёт стоимости и вариантов доставки ничего не бронирует. Подтверждение экспресс-заявки или платформенного оффера уже создаёт реальную доставку и может привести к списанию. [Подключить сервер](#быстрый-старт) · [Посмотреть сценарии](#что-можно-поручить) · [Открыть справочник инструментов](docs/TOOLS.md) --- ## Увидеть работу за минуту > **Вы:** Сколько будет стоить экспресс-доставка букета сегодня к 18:00? > > **Ассистент:** Проверю маршрут и верну предварительную цену, расстояние и ETA. Заявку не создаю. > > **Вы:** Создай заявку, но не подтверждай, если итоговая цена выше 1 000 ₽. > > **Ассистент:** Создам заявку с уникальным `request_id`, дождусь оценки и сравню итоговую цену с лимитом. Поиск курьера без подходящей цены не запускаю. > > **Вы:** Где сейчас курьер и что отправить получателю? > > **Ассистент:** Получу текущую позицию курьера и публичную ссылку на отслеживание для точки вручения. > > **Вы:** Можно отменить заявку бесплатно? > > **Ассистент:** Сначала проверю условия отмены. Ничего не отменю, пока не покажу статус: бесплатно, платно с указанной стоимостью или уже невозможно. > Примеры показывают последовательность доступных инструментов. Конкретные цена, ETA, статусы и доступность доставки всегда приходят из вашего аккаунта Яндекс Доставки. --- ## Содержание - [Быстрый старт](#быстрый-старт) - [Что можно поручить](#что-можно-поручить) - [Где начинается реальный заказ](#где-начинается-реальный-заказ) - [Установка в другие AI-клиенты](#установка-в-другие-ai-клиенты) - [Получение доступа к API](#получение-доступа-к-api) - [Настройка](#настройка) - [Данные и телеметрия](#данные-и-телеметрия) - [Ограничения](#ограничения) - [Документация и разработка](#документация-и-разработка) - [Помощь и обратная связь](#помощь-и-обратная-связь) ## Быстрый старт Нужны Node.js 20+ и токен корпоративного клиента Яндекс Доставки. 1. [Получите токен](#получение-доступа-к-api) в личном кабинете Яндекс Доставки. 2. Добавьте MCP-сервер в Codex: ```bash codex mcp add yandex-dostavka \ --env YANDEX_DELIVERY_TOKEN=ваш_токен \ -- npx -y mcp-yandex-dostavka@latest ``` 3. Начните новую задачу Codex и проверьте подключение безопасным запросом: > Посчитай стоимость экспресс-доставки коробки 2 кг с Льва Толстого, 16 на Тверскую, 7. Ничего не создавай и не подтверждай. Для Claude Code, Claude Desktop, Cursor и VS Code готовые конфигурации находятся в разделе [«Установка в другие AI-клиенты»](#установка-в-другие-ai-клиенты). ## Что можно поручить ### Экспресс-доставка — день в день - **Узнать цену до заказа.** Получить предварительную стоимость, расстояние и ETA без создания заявки — `express_check_price`. - **Создать и подтвердить отправку.** Подготовить экспресс-заявку через `express_create_claim`, проверить оценку через `express_get_claim` и отдельной командой запустить поиск курьера через `express_accept_claim`. - **Найти нужную заявку.** Искать отправления по статусу, телефону, периоду или внешнему номеру заказа — `express_search_claims`. - **Следить за доставкой.** Получить текущую позицию курьера и публичную ссылку для получателя — `express_performer_position`, `express_tracking_links`. - **Отменить с известными последствиями.** Сначала узнать, бесплатна ли отмена и возможна ли она вообще, затем отменить заявку — `express_cancel_info`, `express_cancel_claim`. ### Платформа — другой день, ПВЗ и постаматы - **Найти точку выдачи.** Отобрать ПВЗ, постаматы или точки самопривоза по городу, координатам, типу и способу оплаты — `platform_list_pickup_points`. - **Рассчитать варианты.** Получить офферы с доступными сроками и стоимостью доставки до двери или до точки выдачи — `platform_create_offers`. - **Забронировать доставку.** Подтвердить выбранный оффер и создать заказ — `platform_confirm_offer`. - **Проверить, что происходит с заказом.** Получить текущий статус и историю переходов — `platform_get_request`, `platform_request_history`. - **Отменить заказ.** Отправить запрос на отмену, пока статус это позволяет, — `platform_cancel_request`. ### Остальные методы API `raw_request` вызывает любой относительный путь Экспресса или Платформы. Он нужен для методов, у которых пока нет отдельного инструмента: тарифов, ETA по точкам, редактирования заявок, ярлыков, актов, складов, отгрузок и других операций. > **`raw_request` помечен как разрушительный инструмент.** Он может вызвать не только чтение, но и произвольную запись. Используйте специализированный инструмент, если он уже есть. Полные схемы, форматы денег и единиц измерения, статусы и типовые ошибки собраны в [справочнике инструментов](docs/TOOLS.md). ## Где начинается реальный заказ Яндекс Доставка — write API: некоторые вызовы создают, подтверждают и отменяют настоящие отправления. | Действие | Что происходит | Реальная доставка | |---|---|---| | `express_check_price` | Предварительно рассчитывает цену | Нет | | `express_create_claim` | Создаёт заявку и запускает оценку | Ещё не заказана, если не передан `auto_accept: true` | | `express_accept_claim` | Подтверждает оценённую заявку и запускает поиск курьера | **Да** | | `platform_create_offers` | Рассчитывает варианты и цены | Нет | | `platform_confirm_offer` | Бронирует оффер и создаёт заказ | **Да** | | `express_cancel_claim` | Отменяет заявку; отмена может быть платной | **Да, изменяет заказ** | | `platform_cancel_request` | Отменяет платформенный заказ, если статус позволяет | **Да, изменяет заказ** | Что сервер делает для снижения риска: - `express_cancel_info` показывает условия до отмены: `free`, `paid` с ценой или `unavailable`. - Экспресс-создание использует токен идемпотентности `request_id`, чтобы безопасный повтор не вызвал двух курьеров. - Неидемпотентные записи не повторяются автоматически после сетевой ошибки или ответа 5xx. - Все 16 инструментов содержат MCP-аннотации `readOnlyHint`, `destructiveHint`, `idempotentHint` и `openWorldHint`. **Поведение подтверждений задаёт AI-клиент, а не MCP-сервер.** Одни клиенты всегда спрашивают разрешение на запись, другие используют собственные политики. Для безопасной проверки явно просите ничего не создавать и начинайте с инструментов расчёта или чтения. ## Установка в другие AI-клиенты
Codex
1. Добавьте MCP-сервер: ```bash codex mcp add yandex-dostavka \ --env YANDEX_DELIVERY_TOKEN=ваш_токен \ -- npx -y mcp-yandex-dostavka@latest ``` 2. Начните новую задачу Codex. 3. Проверьте подключение безопасным запросом: > Посчитай стоимость экспресс-доставки коробки 2 кг с Льва Толстого, 16 на Тверскую, 7. Ничего не создавай и не подтверждай.
Claude Code
```bash claude mcp add yandex-dostavka \ -e YANDEX_DELIVERY_TOKEN=ваш_токен \ -- npx -y mcp-yandex-dostavka@latest ```
Claude Desktop
Откройте `claude_desktop_config.json`: на macOS он находится в `~/Library/Application Support/Claude/`, на Windows — в `%APPDATA%\Claude\`. ```json { "mcpServers": { "yandex-dostavka": { "command": "npx", "args": ["-y", "mcp-yandex-dostavka@latest"], "env": { "YANDEX_DELIVERY_TOKEN": "ваш_токен" } } } } ```
Cursor
Добавьте сервер в `~/.cursor/mcp.json` или в `.cursor/mcp.json` проекта: ```json { "mcpServers": { "yandex-dostavka": { "command": "npx", "args": ["-y", "mcp-yandex-dostavka@latest"], "env": { "YANDEX_DELIVERY_TOKEN": "ваш_токен" } } } } ```
VS Code
Создайте `.vscode/mcp.json`. Здесь используется ключ `servers`, а не `mcpServers`: ```json { "servers": { "yandex-dostavka": { "type": "stdio", "command": "npx", "args": ["-y", "mcp-yandex-dostavka@latest"], "env": { "YANDEX_DELIVERY_TOKEN": "ваш_токен" } } } } ```
## Получение доступа к API 1. Зарегистрируйтесь как корпоративный клиент на [dostavka.yandex.ru](https://dostavka.yandex.ru) и заключите договор. Для платформенного контура также подключите станцию отгрузки. 2. В личном кабинете откройте вкладку **«Интеграции»** и нажмите **«Получить токен»**. 3. Передайте токен серверу в `YANDEX_DELIVERY_TOKEN`. Токен действует неограниченное время, но перестаёт работать после смены пароля личного кабинета. Подробнее: [доступ к API Экспресса](https://yandex.ru/support/delivery-profile/ru/api/express/quickstart) и [доступ к API Платформы](https://yandex.ru/support/delivery-profile/ru/api/other-day/access). > **Токен хранится открытым текстом в конфигурации AI-клиента.** Относитесь к нему как к паролю и не добавляйте конфиг с реальным токеном в Git. ### Один или два токена Обычно достаточно общего `YANDEX_DELIVERY_TOKEN`. Если Экспресс и Платформа подключены в разных кабинетах, задайте оба контурных токена: - `YANDEX_DELIVERY_EXPRESS_TOKEN` — переопределяет общий токен для Экспресса; - `YANDEX_DELIVERY_PLATFORM_TOKEN` — переопределяет общий токен для Платформы. Если общего токена нет, серверу нужны оба контурных токена. ### Тестовая среда Тестовый контур есть только у Платформы. Задайте `YANDEX_DELIVERY_PLATFORM_BASE_URL=https://b2b.taxi.tst.yandex.net` и используйте тестовые реквизиты из [официальной инструкции](https://yandex.ru/support/delivery-profile/ru/api/other-day/access). Тестовая среда обрабатывает только московские адреса. У Экспресса тестового окружения нет: создание и подтверждение заявок происходит в рабочем контуре. ## Настройка | Переменная | Обязательна | По умолчанию | Что задаёт | |---|---:|---|---| | `YANDEX_DELIVERY_TOKEN` | да* | — | Общий Bearer-токен для обоих контуров | | `YANDEX_DELIVERY_EXPRESS_TOKEN` | нет | — | Токен Экспресса; переопределяет общий | | `YANDEX_DELIVERY_PLATFORM_TOKEN` | нет | — | Токен Платформы; переопределяет общий | | `YANDEX_DELIVERY_EXPRESS_BASE_URL` | нет | `https://b2b.taxi.yandex.net` | Корневой URL Экспресса | | `YANDEX_DELIVERY_PLATFORM_BASE_URL` | нет | `https://b2b-authproxy.taxi.yandex.net` | Корневой URL Платформы | | `YANDEX_DELIVERY_LANG` | нет | `ru` | Заголовок `Accept-Language` | | `YANDEX_DELIVERY_TIMEOUT_MS` | нет | `60000` | Таймаут одного запроса, мс | | `YANDEX_DELIVERY_MAX_RETRIES` | нет | `3` | Число повторов временных ошибок | | `ASKADS_TELEMETRY` | нет | включена | `0`, `false`, `off` или `no` отключает анонимную телеметрию | \* Общий токен не нужен, если заданы оба контурных. ## Данные и телеметрия ### Запросы к Яндекс Доставке Сервер запускается локально и обращается к API Яндекс Доставки напрямую. Bearer-токен добавляется только к запросам выбранного контура. Даже `raw_request` принимает относительный путь: если он разрешается во внешний хост, запрос блокируется, чтобы токен не ушёл на чужой адрес. ### Анонимная телеметрия По умолчанию сервер отправляет на `usage.gistrec.cloud` три вида технических событий: запуск сервера, имя вызванного инструмента и код причины неудачного запуска. В событие входят случайный идентификатор установки, версия пакета, имя и версия AI-клиента, версия Node.js и операционная система. **Токен, данные аккаунта, аргументы инструментов и тексты запросов не читаются и не отправляются.** Отправка выполняется в фоне с таймаутом 2 секунды и не влияет на работу сервера. Чтобы отключить телеметрию для MCP-серверов Ask Ads, добавьте в конфигурацию: ```text ASKADS_TELEMETRY=0 ``` Реализация находится в [`src/telemetry.ts`](src/telemetry.ts). ## Ограничения - **Это не read-only сервер.** Подтверждение заявки или оффера заказывает доставку; отмена может быть платной. - **AI-клиент влияет на поведение.** MCP-сервер предоставляет инструменты и схемы, но решение о том, когда их вызвать и спросить ли дополнительное подтверждение, принимает клиент и его агент. - **Нет тестового Экспресса.** Безопасно проверить можно расчёт стоимости и чтение существующих заявок; подтверждённая заявка реальна. - **Нет постоянного наблюдения.** Сервер работает только во время вызова из AI-клиента и сам не следит за статусами в фоне. - **Rate limits не опубликованы.** При HTTP 429 сервер делает до заданного числа повторов с задержкой; `Retry-After` учитывается. - **Нет автоматического отката.** Возможность и стоимость отмены зависят от текущего статуса и правил Яндекс Доставки. ## Документация и разработка - [Все инструменты](docs/TOOLS.md) — входные данные, ответы, статусы, ошибки и единицы измерения. - [Разработка](docs/DEVELOPMENT.md) — локальный запуск, тесты, сборка и безопасная smoke-проверка. - [Публикация](docs/PUBLISHING.md) — выпуск npm-пакета и листинг в каталогах MCP. - [npm-пакет](https://www.npmjs.com/package/mcp-yandex-dostavka) — опубликованная версия `mcp-yandex-dostavka`. - [API Экспресса](https://yandex.ru/support/delivery-profile/ru/api/express/openapi/) и [API Платформы](https://yandex.ru/support/delivery-profile/ru/api/other-day/ref/) — официальная документация Яндекс Доставки. Проверить проект локально: ```bash npm install npm run typecheck npm test ``` Тесты не обращаются к сети. `npm run smoke` — отдельная живая read-only проверка с реальным токеном. ## Помощь и обратная связь Нашли ошибку или не хватает сценария? [Создайте issue](https://github.com/A1-x-Tech/mcp-yandex-dostavka/issues) или напишите в Telegram: [@gistrec](https://t.me/gistrec). ## Лицензия MIT — см. [LICENSE](LICENSE).