Yandex Delivery MCP
MCP server for the Yandex Delivery B2B API: express claims, tracking, NDD/pickup-point orders.
Open source Open in the app JSON README (API)
About
MCP server for the Yandex Delivery B2B API: express claims, tracking, NDD/pickup-point orders.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- a1-x-tech
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.1.0
- Last push
- 2026-08-30T13:36:11Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:01:38
- Updated
- 2026-08-29 03:01:38
- Origin id
io.github.A1-x-Tech/mcp-yandex-dostavka
README
# <img src="./assets/a1-logo.svg" alt="A1" width="40"> Яндекс Доставка MCP
[](https://www.npmjs.com/package/mcp-yandex-dostavka)
[](https://github.com/A1-x-Tech/mcp-yandex-dostavka/actions/workflows/ci.yml)
[](https://glama.ai/mcp/servers/A1-x-Tech/mcp-yandex-dostavka)
[](LICENSE)
**A1 Яндекс Доставка MCP** позволяет управлять корпоративной доставкой из Claude, Codex, Cursor и других AI-приложений. Вы ставите задачу обычными словами, а ассистент обращается к вашему аккаунту Яндекс Доставки, рассчитывает стоимость, оформляет отправления и показывает их статус.
- **День в день по городу.** Рассчитайте доставку, вызовите курьера, узнайте его местоположение и получите ссылку для получателя.
- **На следующий день и по России.** Сравните доступные сроки и стоимость доставки до двери.
- **В ПВЗ и постаматы.** Найдите подходящую точку, рассчитайте варианты и оформите выбранную доставку.
- **Сначала расчёт, затем заказ.** Ассистент различает предварительную стоимость, подготовку отправления и момент, когда доставка действительно оформляется.
- **Без собственной интеграции.** Внутри уже есть 16 готовых действий, схемы данных и правила безопасной работы с повторными запросами.
Подходит компаниям и предпринимателям, которые уже подключены к B2B API Яндекс Доставки и получили токен в личном кабинете. Это не сервис для частных отправителей.
**Быстро узнать стоимость**
> **Вы:** Рассчитай доставку коробки 2 кг с Льва Толстого, 16 на Тверскую, 7.
>
> **Ассистент:** Проверил маршрут через Яндекс Доставку и вернул актуальную стоимость, расстояние и примерное время подачи из вашего аккаунта.
[Подключить сервер](#быстрый-старт) · [Посмотреть сценарии](#что-можно-поручить) · [Открыть техническую документацию](#техническая-документация)
---
## Увидеть работу за минуту
> **Вы:** Рассчитай доставку букета сегодня к 18:00 из офиса на Льва Толстого, 16 клиенту на Тверскую, 7.
>
> **Ассистент:** Проверил маршрут и получил предварительную стоимость, расстояние и ETA из вашего аккаунта Яндекс Доставки.
>
> **Вы:** Оформи доставку, если итоговая цена не выше 1 000 ₽.
>
> **Ассистент:** Итоговая цена укладывается в лимит. Доставка оформлена, поиск курьера начался.
>
> **Вы:** Где сейчас курьер и какую ссылку отправить получателю?
>
> **Ассистент:** Получил текущую позицию курьера и публичную ссылку для отслеживания заказа.
>
> **Вы:** Теперь найди варианты доставки этой коробки в Казань на следующий день: до двери, в ПВЗ или постамат.
>
> **Ассистент:** Получил доступные варианты по срокам и стоимости. Для ПВЗ и постаматов покажу адреса, расписание и поддерживаемые способы оплаты.
>
> **Вы:** Можно бесплатно отменить первую доставку?
>
> **Ассистент:** Сначала проверил условия отмены. Покажу, доступна ли она сейчас, будет ли бесплатной и какая сумма спишется при платной отмене.
> Примеры показывают последовательность доступных действий. Конкретные цены, сроки, статусы и доступность доставки всегда приходят из вашего аккаунта Яндекс Доставки.
---
## Содержание
- [Быстрый старт](#быстрый-старт)
- [Что можно поручить](#что-можно-поручить)
- [Как ассистент работает с доставкой](#как-ассистент-работает-с-доставкой)
- [Когда создаётся реальный заказ](#когда-создаётся-реальный-заказ)
- [Получение доступа к API](#получение-доступа-к-api)
- [Технические настройки](#технические-настройки)
- [Данные и телеметрия](#данные-и-телеметрия)
- [Ограничения](#ограничения)
- [Техническая документация](#техническая-документация)
- [Помощь и обратная связь](#помощь-и-обратная-связь)
## Быстрый старт
Нужны Node.js 20+ и токен корпоративного клиента Яндекс Доставки.
1. [Получите токен](#получение-доступа-к-api) в личном кабинете Яндекс Доставки.
2. Добавьте MCP-сервер в своё AI-приложение.
`mcp-yandex-dostavka` запускается на вашем компьютере через `npx`, поэтому браузерные версии ChatGPT и Claude не могут подключить его напрямую.
<details open>
<summary><strong>Codex</strong></summary>
<br>
**Через интерфейс приложения:**
1. Откройте **Settings → MCP servers**.
2. Нажмите **Add server**.
3. Выберите **STDIO**, затем укажите команду запуска `npx -y mcp-yandex-dostavka@latest` и переменную окружения `YANDEX_DELIVERY_TOKEN` со своим токеном.
4. Нажмите **Save**, затем **Restart**.
**Через командную строку:**
```bash
codex mcp add yandex-dostavka \
--env YANDEX_DELIVERY_TOKEN=ваш_токен \
-- npx -y mcp-yandex-dostavka@latest
```
Проверьте подключение:
```bash
codex mcp list
```
Команда сохраняет сервер в общей конфигурации Codex. Если Codex уже открыт, перезапустите его.
[Официальная инструкция Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
</details>
<details>
<summary><strong>Claude Desktop</strong></summary>
<br>
Актуальный официальный путь — **Settings → Extensions**. Для пользовательского desktop extension откройте **Advanced settings → Extension Developer → Install Extension…**, выберите файл `.mcpb` и следуйте подсказкам.
Этот репозиторий сейчас публикует npm-пакет со stdio и пока не содержит `.mcpb`. Поэтому используйте приведённый ниже JSON stdio-конфиг как fallback только в сборках Claude Desktop, где ещё поддерживается локальная конфигурация:
```json
{
"mcpServers": {
"yandex-dostavka": {
"command": "npx",
"args": ["-y", "mcp-yandex-dostavka@latest"],
"env": {
"YANDEX_DELIVERY_TOKEN": "ваш_токен"
}
}
}
}
```
В таких сборках сохраните его в `~/Library/Application Support/Claude/claude_desktop_config.json` на macOS или `%APPDATA%\Claude\claude_desktop_config.json` на Windows.
Сохраните файл и перезапустите Claude Desktop.
[Официальная инструкция Claude Desktop](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)
</details>
<details>
<summary><strong>Claude Code</strong></summary>
<br>
Откройте терминал и выполните:
```bash
claude mcp add \
--env YANDEX_DELIVERY_TOKEN=ваш_токен \
--transport stdio \
--scope user \
yandex-dostavka \
-- npx -y mcp-yandex-dostavka@latest
```
Проверьте подключение:
```bash
claude mcp list
```
[Официальная инструкция Claude Code](https://code.claude.com/docs/en/mcp)
</details>
<details>
<summary><strong>Cursor</strong></summary>
<br>
Пользовательский локальный сервер добавляется в Cursor через файл `mcp.json`:
- macOS и Linux: `~/.cursor/mcp.json`
- Windows: `%USERPROFILE%\.cursor\mcp.json`
Создайте файл, если его ещё нет, и добавьте сервер. Если в файле уже есть другие серверы, сохраните их и добавьте только запись `yandex-dostavka`:
```json
{
"mcpServers": {
"yandex-dostavka": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-yandex-dostavka@latest"],
"env": {
"YANDEX_DELIVERY_TOKEN": "ваш_токен"
}
}
}
}
```
Сохраните файл. Если Cursor уже открыт, перезапустите его.
[Официальная инструкция Cursor](https://cursor.com/docs/mcp)
</details>
<details>
<summary><strong>VS Code</strong></summary>
<br>
1. Откройте палитру команд: `⇧⌘P` на macOS или `Ctrl+Shift+P` на Windows и Linux.
2. Выполните команду **MCP: Open User Configuration**. Откроется пользовательский файл `mcp.json`, доступный во всех проектах.
3. Добавьте сервер. Если в файле уже есть другие настройки, сохраните их:
```json
{
"inputs": [
{
"type": "promptString",
"id": "yandex-delivery-token",
"description": "Токен Яндекс Доставки",
"password": true
}
],
"servers": {
"yandex-dostavka": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-yandex-dostavka@latest"],
"env": {
"YANDEX_DELIVERY_TOKEN": "${input:yandex-delivery-token}"
}
}
}
}
```
4. Сохраните файл. VS Code попросит токен при первом запуске сервера и сохранит его как скрытое значение.
5. Чтобы проверить сервер, выполните в палитре команд **MCP: List Servers** и выберите `yandex-dostavka`.
[Официальная инструкция VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
</details>
После подключения откройте новый диалог в выбранном приложении и попросите:
> Рассчитай доставку коробки 2 кг с Льва Толстого, 16 на Тверскую, 7.
## Что можно поручить
### Доставка день в день по городу
- **Узнать стоимость.** Рассчитать цену, расстояние и примерное время подачи курьера по адресам, весу и габаритам отправления.
- **Оформить отправление.** Передать товары, адреса, контакты и требования к машине или курьеру.
- **Найти заказ.** Искать отправления по статусу, телефону, периоду или номеру заказа вашей компании.
- **Следить за курьером.** Получить его текущую позицию и публичную ссылку для получателя.
- **Отменить с известными последствиями.** Сначала узнать, возможна ли отмена и будет ли она платной.
### Доставка на следующий день и по России
- **Сравнить варианты.** Получить доступные интервалы и стоимость доставки до двери.
- **Оформить выбранный вариант.** Подтвердить подходящие срок, способ вручения и цену.
- **Проверить заказ.** Узнать текущий статус и посмотреть историю его изменений.
- **Отменить заказ.** Отправить запрос на отмену, пока текущий статус это позволяет.
### Доставка в ПВЗ и постаматы
- **Найти подходящую точку.** Искать ПВЗ и постаматы по городу, координатам, типу и способу оплаты.
- **Проверить условия.** Посмотреть адрес, расписание, доступность самопривоза и способы оплаты.
- **Рассчитать и оформить.** Получить варианты доставки в выбранную точку и подтвердить подходящий.
## Как ассистент работает с доставкой
**Для доставки день в день** ассистент сначала рассчитывает маршрут. Когда вы просите оформить отправление, он передаёт данные в Яндекс Доставку, дожидается итоговой оценки и запускает поиск курьера. После этого можно узнавать статус, смотреть позицию курьера и получать ссылку для отслеживания.
**Для доставки на следующий день, по России, в ПВЗ или постамат** ассистент получает доступные варианты со сроками и стоимостью. Вы выбираете подходящий вариант, после чего ассистент оформляет заказ и может читать его текущий статус и историю.
**Значения не придумываются.** Стоимость, ETA, доступные интервалы, адреса точек и статусы приходят из вашего аккаунта Яндекс Доставки.
**Ассистент не наблюдает за заказами постоянно.** Он проверяет состояние доставки, когда вы ставите ему задачу. Если AI-приложение поддерживает задачи по расписанию, в его интерфейсе можно настроить регулярную проверку — например, каждый час узнавать статус заказа до вручения.
## Когда создаётся реальный заказ
| Что вы просите | Что происходит | Доставка оформлена |
|---|---|---|
| Рассчитать доставку день в день | Ассистент получает предварительную цену, расстояние и ETA | Нет |
| Подготовить доставку день в день | Создаётся заявка и получается итоговая оценка, но поиск курьера ещё не начинается | Ещё нет |
| Оформить доставку день в день | Ассистент подтверждает оценённую заявку и запускает поиск курьера | **Да** |
| Рассчитать доставку на следующий день, до ПВЗ или постамата | Ассистент получает доступные варианты и цены | Нет |
| Оформить выбранный вариант | Ассистент подтверждает вариант и создаёт заказ | **Да** |
| Проверить условия отмены | Ассистент узнаёт, возможна ли отмена и сколько она стоит | Нет |
| Отменить доставку | Ассистент изменяет реальный заказ; отмена может быть платной | **Да, заказ изменяется** |
**Точная команда на оформление или отмену разрешает соответствующее действие.** Поведение дополнительных подтверждений зависит от AI-приложения: некоторые клиенты спрашивают разрешение перед каждой записью, другие следуют собственным политикам.
## Получение доступа к 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). Она обрабатывает только московские адреса.
Для доставки день в день тестовой среды нет: безопасно проверять расчёт стоимости и чтение существующих заявок, а оформленные отправления попадают в рабочую систему.
## Технические настройки
На техническом уровне сервер работает с двумя независимыми частями B2B API Яндекс Доставки: API доставки день в день и API доставки на другой день. У них могут быть разные токены, адреса серверов, форматы денег и единицы измерения — MCP-сервер выбирает нужные параметры сам.
| Переменная | Обязательна | По умолчанию | Что задаёт |
|---|---:|---|---|
| `YANDEX_DELIVERY_TOKEN` | да* | — | Общий Bearer-токен для обоих API |
| `YANDEX_DELIVERY_EXPRESS_TOKEN` | нет | — | Отдельный токен доставки день в день |
| `YANDEX_DELIVERY_PLATFORM_TOKEN` | нет | — | Отдельный токен доставки на другой день |
| `YANDEX_DELIVERY_EXPRESS_BASE_URL` | нет | `https://b2b.taxi.yandex.net` | Корневой URL API доставки день в день |
| `YANDEX_DELIVERY_PLATFORM_BASE_URL` | нет | `https://b2b-authproxy.taxi.yandex.net` | Корневой URL API доставки на другой день |
| `YANDEX_DELIVERY_LANG` | нет | `ru` | Заголовок `Accept-Language` |
| `YANDEX_DELIVERY_TIMEOUT_MS` | нет | `60000` | Таймаут одного запроса, мс |
| `YANDEX_DELIVERY_MAX_RETRIES` | нет | `3` | Число повторов временных ошибок |
| `ASKADS_TELEMETRY` | нет | включена | `0`, `false`, `off` или `no` отключает анонимную телеметрию |
\* Общий токен не нужен, если заданы оба отдельных токена.
## Данные и телеметрия
### Запросы к Яндекс Доставке
Сервер запускается локально и обращается к API Яндекс Доставки напрямую. Bearer-токен добавляется только к запросам выбранного API. Даже универсальный инструмент принимает относительный путь: если он ведёт на внешний сервер, запрос блокируется, чтобы токен не ушёл на чужой адрес.
### Анонимная телеметрия
По умолчанию сервер отправляет на `usage.gistrec.cloud` три вида технических событий: запуск сервера, имя вызванного инструмента и код причины старта без настроенного токена.
В событие входят случайный идентификатор установки, версия пакета, имя и версия AI-приложения, версия Node.js и операционная система. **Токен, данные аккаунта, аргументы инструментов и тексты запросов не читаются и не отправляются.** Отправка выполняется в фоне с таймаутом 2 секунды и не влияет на работу сервера.
Чтобы отключить телеметрию для MCP-серверов A1, добавьте в конфигурацию:
```text
ASKADS_TELEMETRY=0
```
Реализация находится в [`src/telemetry.ts`](src/telemetry.ts).
## Ограничения
- **Это не только чтение.** Ассистент умеет оформлять и отменять настоящие доставки; отмена может быть платной.
- **AI-приложение влияет на подтверждения.** MCP-сервер сообщает тип каждого действия, но решение о дополнительном вопросе перед записью принимает приложение и его агент.
- **Нет тестовой среды для доставки день в день.** Безопасно проверить можно расчёт стоимости и чтение существующих заявок.
- **Нет постоянного наблюдения.** Сервер работает во время вызова из AI-приложения. Если приложение поддерживает задачи по расписанию, настройте в его интерфейсе регулярную проверку статуса.
- **При временном ограничении возможна задержка.** Сервер сам подождёт и повторит запрос. Если Яндекс Доставка по-прежнему недоступна, попробуйте ещё раз позже.
- **Нет автоматического отката.** Возможность и стоимость отмены зависят от текущего статуса и правил Яндекс Доставки.
## Техническая документация
- [Каталог 16 MCP-возможностей](docs/capabilities/index.md) — отдельные страницы инструментов на языке пользовательских задач.
- [Технический справочник инструментов](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/) — официальная документация Яндекс Доставки.
## Помощь и обратная связь
Нашли ошибку или не хватает сценария? [Создайте issue](https://github.com/A1-x-Tech/mcp-yandex-dostavka/issues) или напишите в [Telegram](https://t.me/a1_mcp).
<br>
<p align="center">
<img src="https://github.com/ztemerbekov/a1-yandex-kit-skills/raw/main/assets/images/mona-hifive-yandex-kit-warm.gif" alt="Две Моны дают пять" width="256">
</p>
<p align="center">
Вы дочитали до конца!
</p>