Скажите, что и куда доставить, — AI-ассистент рассчитает, оформит и даст трекинг

<img src="./assets/a1-logo.svg" alt="A1" width="22"> Яндекс Доставка 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. Заявка создана не будет.

Подготовить отправку, но пока не вызывать курьера

Вы: Создай экспресс-заявку по этим данным, дождись оценки, но не подтверждай её.

Ассистент: Заявка создана и оценена. Покажу итоговую цену и статус; поиск курьера не запущен.

Вы управляете границей между расчётом и реальным заказом. Расчёт стоимости и вариантов доставки ничего не бронирует. Подтверждение экспресс-заявки или платформенного оффера уже создаёт реальную доставку и может привести к списанию.

Подключить сервер · Посмотреть сценарии · Открыть справочник инструментов

---

Увидеть работу за минуту

Вы: Сколько будет стоить экспресс-доставка букета сегодня к 18:00?

Ассистент: Проверю маршрут и верну предварительную цену, расстояние и ETA. Заявку не создаю.

Вы: Создай заявку, но не подтверждай, если итоговая цена выше 1 000 ₽.

Ассистент: Создам заявку с уникальным request_id, дождусь оценки и сравню итоговую цену с лимитом. Поиск курьера без подходящей цены не запускаю.

Вы: Где сейчас курьер и что отправить получателю?

Ассистент: Получу текущую позицию курьера и публичную ссылку на отслеживание для точки вручения.

Вы: Можно отменить заявку бесплатно?

Ассистент: Сначала проверю условия отмены. Ничего не отменю, пока не покажу статус: бесплатно, платно с указанной стоимостью или уже невозможно.

Примеры показывают последовательность доступных инструментов. Конкретные цена, ETA, статусы и доступность доставки всегда приходят из вашего аккаунта Яндекс Доставки.

---

Содержание

• Быстрый старт
• Что можно поручить
• Где начинается реальный заказ
• Установка в другие AI-клиенты
• Получение доступа к API
• Настройка
• Данные и телеметрия
• Ограничения
• Документация и разработка
• Помощь и обратная связь

Быстрый старт

Нужны Node.js 20+ и токен корпоративного клиента Яндекс Доставки.

1. Получите токен в личном кабинете Яндекс Доставки.

2. Добавьте MCP-сервер в Codex:

   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-клиенты».

Что можно поручить

Экспресс-доставка — день в день

• Узнать цену до заказа. Получить предварительную стоимость, расстояние и 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 помечен как разрушительный инструмент. Он может вызвать не только чтение, но и произвольную запись. Используйте специализированный инструмент, если он уже есть.

Полные схемы, форматы денег и единиц измерения, статусы и типовые ошибки собраны в справочнике инструментов.

Где начинается реальный заказ

Яндекс Доставка — 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-клиенты

<details open> <summary><strong>Codex</strong></summary>

<br>

1. Добавьте MCP-сервер:

   codex mcp add yandex-dostavka \
     --env YANDEX_DELIVERY_TOKEN=ваш_токен \
     -- npx -y mcp-yandex-dostavka@latest
   

2. Начните новую задачу Codex.

3. Проверьте подключение безопасным запросом:

   Посчитай стоимость экспресс-доставки коробки 2 кг с Льва Толстого, 16 на Тверскую, 7. Ничего не создавай и не подтверждай.

</details>

<details> <summary><strong>Claude Code</strong></summary>

<br>

claude mcp add yandex-dostavka \
  -e YANDEX_DELIVERY_TOKEN=ваш_токен \
  -- npx -y mcp-yandex-dostavka@latest

</details>

<details> <summary><strong>Claude Desktop</strong></summary>

<br>

Откройте claude_desktop_config.json: на macOS он находится в ~/Library/Application Support/Claude/, на Windows — в %APPDATA%\Claude\.

{
  "mcpServers": {
    "yandex-dostavka": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-dostavka@latest"],
      "env": {
        "YANDEX_DELIVERY_TOKEN": "ваш_токен"
      }
    }
  }
}

</details>

<details> <summary><strong>Cursor</strong></summary>

<br>

Добавьте сервер в ~/.cursor/mcp.json или в .cursor/mcp.json проекта:

{
  "mcpServers": {
    "yandex-dostavka": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-dostavka@latest"],
      "env": {
        "YANDEX_DELIVERY_TOKEN": "ваш_токен"
      }
    }
  }
}

</details>

<details> <summary><strong>VS Code</strong></summary>

<br>

Создайте .vscode/mcp.json. Здесь используется ключ servers, а не mcpServers:

{
  "servers": {
    "yandex-dostavka": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-dostavka@latest"],
      "env": {
        "YANDEX_DELIVERY_TOKEN": "ваш_токен"
      }
    }
  }
}

</details>

Получение доступа к API

1. Зарегистрируйтесь как корпоративный клиент на dostavka.yandex.ru и заключите договор. Для платформенного контура также подключите станцию отгрузки.
2. В личном кабинете откройте вкладку «Интеграции» и нажмите «Получить токен».
3. Передайте токен серверу в YANDEX_DELIVERY_TOKEN.

Токен действует неограниченное время, но перестаёт работать после смены пароля личного кабинета. Подробнее: доступ к API Экспресса и доступ к API Платформы.

Токен хранится открытым текстом в конфигурации AI-клиента. Относитесь к нему как к паролю и не добавляйте конфиг с реальным токеном в Git.

Один или два токена

Обычно достаточно общего YANDEX_DELIVERY_TOKEN. Если Экспресс и Платформа подключены в разных кабинетах, задайте оба контурных токена:

• YANDEX_DELIVERY_EXPRESS_TOKEN — переопределяет общий токен для Экспресса;
• YANDEX_DELIVERY_PLATFORM_TOKEN — переопределяет общий токен для Платформы.

Если общего токена нет, серверу нужны оба контурных токена.

Тестовая среда

Тестовый контур есть только у Платформы. Задайте YANDEX_DELIVERY_PLATFORM_BASE_URL=https://b2b.taxi.tst.yandex.net и используйте тестовые реквизиты из официальной инструкции. Тестовая среда обрабатывает только московские адреса.

У Экспресса тестового окружения нет: создание и подтверждение заявок происходит в рабочем контуре.

Настройка

Переменная	Обязательна	По умолчанию	Что задаёт
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, добавьте в конфигурацию:

ASKADS_TELEMETRY=0

Реализация находится в src/telemetry.ts.

Ограничения

• Это не read-only сервер. Подтверждение заявки или оффера заказывает доставку; отмена может быть платной.
• AI-клиент влияет на поведение. MCP-сервер предоставляет инструменты и схемы, но решение о том, когда их вызвать и спросить ли дополнительное подтверждение, принимает клиент и его агент.
• Нет тестового Экспресса. Безопасно проверить можно расчёт стоимости и чтение существующих заявок; подтверждённая заявка реальна.
• Нет постоянного наблюдения. Сервер работает только во время вызова из AI-клиента и сам не следит за статусами в фоне.
• Rate limits не опубликованы. При HTTP 429 сервер делает до заданного числа повторов с задержкой; Retry-After учитывается.
• Нет автоматического отката. Возможность и стоимость отмены зависят от текущего статуса и правил Яндекс Доставки.

Документация и разработка

• Все инструменты — входные данные, ответы, статусы, ошибки и единицы измерения.
• Разработка — локальный запуск, тесты, сборка и безопасная smoke-проверка.
• Публикация — выпуск npm-пакета и листинг в каталогах MCP.
• npm-пакет — опубликованная версия mcp-yandex-dostavka.
• API Экспресса и API Платформы — официальная документация Яндекс Доставки.

Проверить проект локально:

npm install
npm run typecheck
npm test

Тесты не обращаются к сети. npm run smoke — отдельная живая read-only проверка с реальным токеном.

Помощь и обратная связь

Нашли ошибку или не хватает сценария? Создайте issue или напишите в Telegram: @gistrec.

Лицензия

MIT — см. LICENSE.