[Документация Yandex Cloud](../../index.md) > [Yandex Managed Service for YDB](../index.md) > [Пошаговые инструкции](index.md) > Работа с YDB через ydb-mcp сервер на примере IDE Cursor

# Как использовать LLM для работы с Yandex Managed Service for YDB через MCP-сервер: пример на IDE Cursor

Из этой статьи вы узнаете, как можно применять языковые модели (LLM) для работы с базой данных YDB. Это позволит работать с базой на человеческом языке: исправлять ошибки, оптимизировать, проводить анализ данных.

В качестве примера мы рассмотрим работу с облачной, или установленной локально версией YDB, к которой вы будете подключаться с помощью локально установленного MCP-cервера. Для взаимодействия с MCP-сервером мы используем IDE Cursor, а обработку естественного языка обеспечит подключенная LLM-модель. Таким образом, вы сможете легко писать и отправлять запросы на привычном вам языке, а модель в связке с MCP-сервером будет преобразовывать их в корректные SQL-запросы для YDB, помогать с исправлением ошибок и оптимизацией.

- [Используемые термины](#terms)
- [Перед началом работы](#before-start)
- [Подготовка окружения](#prepare)
- [Работа с YDB-mcp](#ydb-mcp-examples)
- [Промпты для экспериментов](#prompts)
- [Итоги](#results)
- [Удаление ресурсов](#delete-resources)


## Используемые термины {#terms}

**[Cursor](https://cursor.com/)** — IDE, имеющая встроенную интеграцию с LLM.

**LLM (Large Language Model)** — большая языковая модель. Пример такой модели — YandexGPT. Она может генерировать текст, но сама по себе не может подключаться к внешним сервисам, например к базе данных. Для этого используется MCP-клиент (например, `Cursor`), который подключается к MCP-серверу, а MCP-сервер взаимодействует с базой данных.  

**MCP (Model Context Protocol)** — открытый протокол, по которому MCP-клиент подключается к MCP-серверу и обеспечивает доступ LLM к внешним сервисам. Подробнее можно почитать на [отдельной странице документации](../../glossary/mcp.md), посвященной MCP.

**MCP-клиент** — программа, которая соединяет LLM с MCP-сервером и добавляет инструменты MCP-сервера к диалогу, чтобы LLM могла их использовать. В этой статье в роли MCP-клиента используется IDE `Cursor`.  

**MCP-сервер** — отдельное приложение, которое подключается к внешнему сервису (в нашем случае — к YDB) и дает доступ к набору инструментов. В самом MCP-сервере нет никакой "интеллектуальной" логики — он просто обеспечивает связь между языковой моделью (LLM) и внешним сервисом. Какие инструменты будут вызваны и как именно — решает LLM и тот запрос, который вы ей задаёте (промпт). Разные LLM могут по-разному подходить к решению задачи: одна сразу составит правильный YQL-запрос, другая будет пробовать разные варианты и исправлять ошибки в процессе.

**ydb-mcp** — это реализация MCP-сервера, разработанная командой YDB. 

Для разных операций ydb-mcp предлагает разные инструменты, например: `ydb_status` проверяет подключение, `ydb_query` выполняет запросы. Эти инструменты похожи на API-функции: вы передаёте им параметры, а в ответ получаете результат.

Аналогично и с разработчиками: при одном и том же API код у каждого будет разный. В случае с LLM результат зависит не только от MCP-сервера, но и от возможностей модели.

## Перед началом работы {#before-start}


### Ресурсы, требующие оплаты {#paid-resources}

1. Учетная запись в [IDE Cursor](https://cursor.com/) (можно использовать пробную версию).
1. Оплата за использование YDB — операции с базой и хранение данных ([тарифы Yandex Managed Service for YDB](../pricing/serverless.md)).

{% note info %}

Все описанное можно применять и с другими IDE или моделями. Cursor выбран здесь как готовое решение, чтобы не отвлекаться на настройку.

{% endnote %}

## Подготовка окружения {#prepare}

1. Установите [IDE Cursor](https://cursor.com/).
2. Установите [Docker Desktop](https://www.docker.com/products/docker-desktop/) или [Docker Engine (CE)](https://docs.docker.com/engine/install/) вместе с плагином [Docker Compose](https://docs.docker.com/compose/install/) — он потребуется для запуска проекта.


### Склонируйте и откройте проект {#copy-and-open-project}

1. Склонируйте проект из репозитория [ydb-mcp-demo-notes](https://github.com/ydb-platform/ydb-mcp-demo-notes). Если Git не установлен, скачайте и распакуйте архив: [main.zip](https://github.com/ydb-platform/ydb-mcp-demo-notes/archive/refs/heads/main.zip).
1. Откройте папку проекта в IDE Cursor: в меню **File** выберите **Open Folder** и укажите папку с проектом.
1. Откройте терминал (меню *View → Terminal* или сочетание клавиш **Ctrl/Cmd** + **Backtick**).
1. Находясь в папке проекта, выполните команду в терминале `docker compose build` — она соберет контейнеры проекта.


### Создайте базу данных Managed Service for YDB {#create-db}

Создайте базу данных в [режиме Serverless](../concepts/serverless-and-dedicated.md#serverless). Это удобный вариант в облаке. Для локальных экспериментов можно запустить [docker-контейнер](https://ydb.tech/docs/ru/quickstart) (вкладка Docker x86_64):

   {% list tabs group=instructions %}

   - Консоль управления {#console}

     1. В [консоли управления](https://console.yandex.cloud) выберите каталог для создания базы.
     1. Перейдите в сервис **Managed Service for YDB**.
     1. Нажмите кнопку **Создать базу данных**.
     1. Введите **Имя** базы. Требования к имени:

        * длина — от 3 до 63 символов;
        * может содержать строчные буквы латинского алфавита, цифры и дефисы;
        * первый символ — буква, последний — не дефис.

     1. В блоке **Тип базы данных** выберите `Serverless`.
     1. Нажмите кнопку **Создать базу данных**.
     1. Дождитесь запуска базы данных. В процессе создания база будет иметь статус `Provisioning`, а когда станет готова к использованию, статус изменится на `Running`.
     1. Выберите созданную базу данных.
     1. В блоке **Соединение** найдите поля **Эндпоинт** и **Путь к базе данных**, сохраните их значения. Они потребуются для настройки подключения к базе.

   - Командная строка (YC CLI) {#cli}

     Базу YDB можно создать с помощью вызова утилиты командной строки `yc`.

     ```
     yc ydb database create test --serverless
     ```

   {% endlist %}


### Создайте авторизованный ключ {#create-key}

При работе с локальным Docker-контейнером пропустите этот раздел.

 [Создайте](../../iam/operations/sa/create.md#create-sa) сервисный аккаунт и [назначьте](../../iam/operations/roles/grant.md#cloud-or-folder) ему роль `ydb.editor` на ваш каталог. В нашем примере потребуется изменение базы со стороны LLM, когда этого не требуется — безопаснее давать роль `ydb.viewer`.

{% list tabs group=instructions %}

- Консоль управления {#console}

  1. В [консоли управления](https://console.yandex.cloud) выберите каталог, которому принадлежит сервисный аккаунт.
  1. Перейдите в сервис **Identity and Access Management**.
  1. На панели слева выберите ![FaceRobot](../../_assets/console-icons/face-robot.svg) **Сервисные аккаунты**.
  1. В открывшемся списке выберите созданный сервисный аккаунт.
  1. Нажмите кнопку **Создать новый ключ** на верхней панели.
  1. Выберите пункт **Создать авторизованный ключ**.
  1. Выберите алгоритм шифрования.
  1. Задайте описание [авторизованного ключа](../../iam/concepts/authorization/key.md), чтобы потом было проще найти его в консоли управления.
  1. Сохраните ключ в файл `authorized_key.json` в папке проекта:

     ```json
     {
       "service_account_id": "<идентификатор_сервисного_аккаунта_sa-function>",
       "key_algorithm": "RSA_2048",
       "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n",
       "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
     }
     ```

- CLI {#cli}

  Выполните команду в терминале, находясь в папке проекта:

  ```bash
  yc iam key create --service-account-name sa-function -o authorized_key.json
  ```

  Подробнее о команде `yc iam key create` читайте в [справочнике CLI](../../cli/cli-ref/iam/cli-ref/key/create.md).

  В случае успеха ключ будет сохранен в файле `authorized_key.json`.

{% endlist %}


{% note warning %}

Файл `authorized_key.json` содержит секретную часть ключа, по которому можно получить доступ к базам данных в вашем каталоге. Храните его в безопасности. В демонстрационном проекте он уже добавлен в `.gitignore`.

{% endnote %}

### Пропишите настройки подключения к базе в ydb.env {#connection-settings-env}

При работе с локальным Docker-контейнером пропустите этот раздел.

1. Скопируйте файл `ydb-template.env` в `ydb.env`
1. Заполните параметры для подключения к созданной ранее базе данных:
    - `YDB_AUTH_MODE=service-account`, имя ключа `authorized_key.json` встроено в пример, и указывать его не нужно.
    - `YDB_ENDPOINT` и `YDB_DATABASE` — возьмите значения из информации о созданной базе.


### Проверьте работу приложения {#check-app}

В терминале IDE Cursor, находясь в папке проекта, выполните команды для проверки работы приложения. После каждого шага убедитесь, что команды выполняются без ошибок:

```
docker compose run --rm notes-app init
docker compose run --rm notes-app add "Тест" "Это моя первая заметка в YDB-notes"
docker compose run --rm notes-app list
```


### Запустить MCP-сервер {#mcp-start}

Параметры запуска MCP-сервера уже заданы в демонстрационном проекте в файле `.cursor/mcp.json`. Если же вам интересно разобраться и попробовать запустить сервер самостоятельно, подробности есть в [документации ydb-mcp](https://github.com/ydb-platform/ydb-mcp).

1. Откройте меню **Cursor Settings** (не путайте с **VS Code Settings**).
1. Перейдите в раздел **MCP & Settings**.
1. Включите переключатель рядом с **ydb**. Если он уже включен, выключите и включите снова — это перезапустит MCP-сервер с новыми настройками.
1. После запуска рядом с MCP-сервером **ydb** появится список инструментов и значок активности.
1. Проверьте работу подключения: откройте AI-панель справа (клавиши **Ctrl/Cmd** + **L**) и в чате введите: «Проверь подключение к YDB». Должен появиться результат, сообщающий о том, что подключение работает корректно.


### Выберите модель {#select-model}

Если у вас пробный аккаунт, то пропустите этот раздел, так как модель выбрать не получится. В режиме Auto все приведенные примеры тоже работают, но модель может выполнять больше действий, а результат будет менее предсказуемым.

В окне чата под полем ввода найдите надпись **Auto**, нажмите на нее и в появившемся окне выключите автоподбор.

Откроется список доступных моделей — выберите модель из семейства `claude-`, например `claude-4-sonnet` или более новую.

Работа MCP-сервера не зависит от выбранной LLM. А вот путь и результат напрямую зависят от конкретной модели: именно она определяет, какие действия будут выполняться через MCP. Примеры в статье проверялись на `claude-4-sonnet` и в режиме `Auto`, но можно попробовать и другие модели.


## Работа с YDB-MCP {#ydb-mcp-examples}


### Наполнение таблицы тестовыми данными через MCP-сервер {#test-data-with-mcp}

Иногда нужно заполнить пустую базу тестовыми данными. Это можно поручить LLM: она сгенерирует данные и через MCP-сервер добавит их в базу.

Пример команды для LLM:

```
Создай 15 тестовых заметок и запиши их в YDB, даты заметок должны быть в пределах `2001-01-01` — `2001-12-31`. Заметки сделай на русском и английском языках.
```

Разберем, как это работает:

1. Cursor передает модели описание MCP-сервера и его инструментов.
1. Через инструмент `ydb_status` LLM проверяет подключение к базе.  
1. Через `ydb_query` LLM отправляет запросы на добавление строк. Здесь требуется корректный YQL-запрос: иногда он не проходит с первого раза. В этом случае модель переписывает запрос с учетом текста ошибки и пробует снова. Количество попыток зависит от конкретной модели и качества запроса. Процесс не требует вашего вмешательства: модель сама исправляет ошибки и в итоге добавляет нужное число заметок.

Чтобы убедиться в результате, выполните команду `docker compose run --rm notes-app list`. Вы увидите заметки, созданные LLM. Таким же способом можно наполнять и более сложные базы.


### Устранение ошибки с помощью MCP-сервера {#fix-code-with-mcp}

LLM могут помогать не только в написании кода или заполнении базы, но и в исправлении ошибок. Это может касаться и данных, и схемы базы, и исходного кода приложения. Чтобы показать, как это работает, мы специально вызовем ошибку: **переименуем таблицу** в базе.

Без MCP у LLM есть только исходный код и текст ошибки. В этом случае она предложит заново выполнить команду инициализации или создать таблицу с помощью запроса. С MCP возможностей больше: модель может запросить схему базы и выполнить любые операции — например, переименовать таблицу обратно или скопировать ее.


#### Исправление схемы базы данных {#fix-database-with-mcp}

Чтобы смоделировать ошибку, переименуйте таблицу:
1. В [консоли управления](https://console.yandex.cloud) выберите каталог, в котором находится БД.
1. Перейдите в сервис **Managed Service for&nbsp;YDB** и откройте свою базу.
1. Нажмите кнопку **Навигация**, а потом **Новый SQL-запрос** и выполните запрос для [переименования таблицы](https://ydb.tech/docs/ru/yql/reference/syntax/alter_table/rename):

```
ALTER TABLE notes RENAME TO notes2
```

После этого выполните `docker compose run --rm notes-app list` и убедитесь, что выводится ошибка.

Начните новый чат в Cursor и отправьте в него задачу: 

```
После моих экспериментов приложение перестало выводить заметки. Проверь базу и почини так, чтобы снова работало. Код менять не надо. Ошибка: <сюда скопируйте текст ошибки>
```

{% note info %}

Cursor не показывает в чате текст, скопированный из собственного терминала — ошибка будет отображаться как ссылка в заголовке окна.

{% endnote %}

LLM через MCP проверит текущее состояние базы, увидит переименованную таблицу и попытается исправить ситуацию. Это может быть возврат старого имени, создание новой таблицы с переносом данных или миграция. При разных запусках модель может выбрать разные способы.


#### Адаптация исходного кода под изменения в схеме  

Удалите временную таблицу `notes2`, если она осталась после предыдущего шага, чтобы она не влияла на дальнейшие проверки:

```
DROP TABLE IF EXISTS notes2
```

Теперь снова [переименуйте](https://ydb.tech/docs/ru/yql/reference/syntax/alter_table/rename) основную таблицу:

```
ALTER TABLE notes RENAME TO notes_new
```

Откройте новый чат и дайте команду:

```
Имя таблицы в YDB изменилось. Поправь исходный код программы для использования нового имени и проверь, что все команды из инструкции продолжают работать.
```


### Сбор аналитики по подключенной базе данных {#mcp-analytics}

LLM с ydb-mcp подходит не только для модификации данных, но и для аналитических запросов — например, чтобы быстро получить сводку или посчитать статистику прямо в базе.

- Посчитай распределение времени создания заметок по часам суток (количество заметок для каждого часа).
- Вычисли среднее и медиану длины заметок; расчеты выполни через YQL на стороне сервера.


## Промпты для экспериментов {#prompts}

Сценарии применения MCP-сервера ydb-mcp шире, чем рассмотренные в этой статье. Доступ LLM к реальной схеме и данным в базе открывает новые возможности для совместной работы. Ниже я покажу примеры еще нескольких типов задач для экспериментов.

- Мой запрос `<...>` работает медленно, найди способы его ускорения
- Создай функции-обертки для доступа к записям в таблице notes.
- Создай функции CRUD для таблиц моей базы.
- Добавь возможность хранить вложения к заметкам. Расскажи, как это можно реализовать с учетом текущей схемы базы.


## Итоги {#results}

Сегодня LLM умеют решать широкий круг задач, но сами по себе они не могут взаимодействовать с внешним миром. MCP обеспечивает такую связку. При использовании YDB MCP-сервера у LLM появляется доступ к базе данных и возможность с ней взаимодействовать. Теперь можно использовать не только схему базы из исходного кода, но и ее фактическое состояние. Например, LLM может изменять схему и данные базы.

{% note warning %}

Используйте LLM с осторожностью и не подключайтесь к критически важным базам данных. Через MCP-сервер LLM получает те права, которые назначены сервисному аккаунту. Лучше сделать копию базы и исследовать копию. Например, в ходе работы модель может отправить запрос на удаление всех данных или выполнение очень тяжелого запроса, который будет мешать работе основной нагрузки.

{% endnote %}


## Удаление ресурсов {#delete-resources}

Чтобы освободить ресурсы, удалите тестовую базу YDB по [инструкции](manage-databases.md#delete-db).