mcp-yandex-dostavka

# <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)
[![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)
[![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)
[![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 → Plugins → MCP servers**.
2. Нажмите **Add server**.
3. Добавьте команду запуска `npx -y mcp-yandex-dostavka@latest` и переменную окружения `YANDEX_DELIVERY_TOKEN` со своим токеном.

**Через командную строку:**

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

Проверьте подключение:

```bash
codex mcp list
```

Команда сохраняет сервер в общей конфигурации Codex. Если Codex уже открыт, перезапустите его.

[Официальная инструкция Codex](https://developers.openai.com/codex/mcp/)

</details>

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

<br>

1. Откройте Claude Desktop и перейдите в **Settings → Developer**.
2. Нажмите **Edit Config**. Claude откроет файл настроек в текстовом редакторе.
3. Добавьте в него MCP-сервер. Если в файле уже есть другие серверы, сохраните их и добавьте только запись `yandex-dostavka`:

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

4. Сохраните файл и перезапустите Claude Desktop.

Если кнопки **Edit Config** нет, откройте файл напрямую:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

[Официальная инструкция Claude Desktop](https://claude.com/docs/connectors/building/mcp-apps/getting-started)

</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.

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

### Доставка день в день по городу

- **Узнать стоимость.** Рассчитать цену, расстояние и примерное время подачи курьера по адресам, весу и габаритам отправления.
- **Оформить отправление.** Передать товары, адреса, контакты и требования к машине или курьеру.
- **Найти заказ.** Искать отправления по статусу, телефону, периоду или номеру заказа вашей компании.
- **Следить за курьером.** Получить его текущую позицию и публичную ссылку для получателя.
- **Отменить с известными последствиями.** Сначала узнать, возможна ли отмена и будет ли она платной.

### Доставка на следующий день и по России

- **Сравнить варианты.** Получить доступные интервалы и стоимость доставки до двери.
- **Оформить выбранный вариант.** Подтвердить подходящие срок, способ вручения и цену.
- **Проверить заказ.** Узнать текущий статус и посмотреть историю его изменений.
- **Отменить заказ.** Отправить запрос на отмену, пока текущий статус это позволяет.

### Доставка в ПВЗ и постаматы

- **Найти подходящую точку.** Искать ПВЗ и постаматы по городу, координатам, типу и способу оплаты.
- **Проверить условия.** Посмотреть адрес, расписание, доступность самопривоза и способы оплаты.
- **Рассчитать и оформить.** Получить варианты доставки в выбранную точку и подтвердить подходящий.

## Как ассистент работает с доставкой

**Для доставки день в день** ассистент сначала рассчитывает маршрут. Когда вы просите оформить отправление, он передаёт данные в Яндекс Доставку, дожидается итоговой оценки и запускает поиск курьера. После этого можно узнавать статус, смотреть позицию курьера и получать ссылку для отслеживания.

**Для доставки на следующий день, по России, в ПВЗ или постамат** ассистент получает доступные варианты со сроками и стоимостью. Вы выбираете подходящий вариант, после чего ассистент оформляет заказ