# <img src="./assets/a1-logo.svg" alt="A1" width="40">&nbsp;Яндекс Доставка MCP

[![npm](https://img.shields.io/npm/v/mcp-yandex-dostavka)](https://www.npmjs.com/package/mcp-yandex-dostavka)
[![Glama](https://glama.ai/mcp/servers/A1-x-Tech/mcp-yandex-dostavka/badges/score.svg)](https://glama.ai/mcp/servers/A1-x-Tech/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** позволяет управлять корпоративной доставкой из 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>