Блог Интеграм Открыть Интеграм
№ 082
20 октября 2026
Обучение
10 мин чтения
← Архив выпусков

Подключаем Claude к базе данных через MCP: инструкция

Как подключить Claude Desktop и Claude Code к базе Интеграма через MCP-сервер integram-mcp: конфиг, команды, проверка и что делать, если сервер не добавился.

Подключаем Claude к базе данных через MCP: инструкция

Попросить Claude «найди всех клиентов без сделок за квартал и поставь каждому задачу на звонок» и получить сделанную работу, а не совет, можно, только если у ассистента есть доступ к вашей базе. Для этого и придуман MCP. Сам протокол и его отличие от обычного API мы разобрали в статье базы знаний «MCP-сервер простыми словами». Здесь — практика: как подключить Claude к базе данных Интеграма через MCP-сервер, как проверить, что всё заработало, и что делать, если клиент пишет, что не удалось добавить сервер.

Инструкция подходит для двух клиентов: Claude Code (командная строка) и Claude Desktop (приложение для macOS и Windows). Cursor и другие клиенты с поддержкой MCP настраиваются почти так же: тот же блок JSON, другой файл.

Что понадобится

  • Node.js. MCP-сервер Интеграма распространяется как npm-пакет integram-mcp (открытый, лицензия MIT) и запускается через npx. Проверьте в терминале: node --version. Если команды нет, поставьте LTS-версию с nodejs.org — её же рекомендует официальная документация MCP.
  • Адрес вашего Интеграма. Облачного или развёрнутого на своём сервере. В документации пакета для облака приведён https://ai2o.online, для локальной установки — http://localhost:8081.
  • Отдельный пользователь для агента. Не ваша учётка администратора, а отдельный логин и пароль с ролью под задачу.
  • Claude Desktop или Claude Code, обновлённые до свежей версии.

Шаг 1. Заведите пользователя для агента

Это самый важный шаг, и его чаще всего пропускают. MCP-сервер Интеграма не открывает ИИ «доступ к базе вообще»: при запуске он входит в систему под конкретным пользователем, и каждое действие агента проходит ту же серверную проверку прав, что и действие человека. Роли, доступ к таблицам, колонкам и отдельным записям работают как обычно.

Отсюда правило: отдельная учётная запись и самая узкая роль, которая решает задачу. Для экспериментов — полные права в тестовом пространстве. Для рабочей базы — например, только чтение нужных таблиц. Как устроены роли и доступ к записям, подробно описано в статье «Права доступа».

Шаг 2. Подключите сервер к Claude Code

В Claude Code сервер добавляется одной командой. Пример из документации пакета integram-mcp:

claude mcp add integram \
  -e INTEGRAM_URL=https://ai2o.online \
  -e INTEGRAM_EMAIL=agent@example.com \
  -e INTEGRAM_PASSWORD=пароль-агента \
  -- npx -y integram-mcp@0.7.124

Разберём по частям:

  • integram — имя сервера, под ним он будет виден в клиенте;
  • -e передаёт серверу переменные окружения: адрес, логин и пароль агента;
  • -- отделяет опции Claude Code от команды запуска сервера. Всё, что после него, уходит серверу без изменений;
  • npx -y integram-mcp@0.7.124 скачивает и запускает пакет. Ставить заранее ничего не нужно.

Номер версии обязателен. Авторы пакета прямо предупреждают: не пишите integram-mcp@latest. npx кэширует пакет по строке запуска и может годами запускать старую сборку под тем же именем. К тому же сервер по stdio работает на вашей машине с вашими правами, и плавающая версия означает «запускать свежий чужой код при каждом старте клиента». Актуальный номер смотрите на странице пакета; 0.7.124 в примере — версия на момент написания статьи. О выходе новой версии сервер сообщит сам, а обновление остаётся вашим решением.

По умолчанию Claude Code добавляет сервер только для текущего проекта (--scope local). Чтобы он был доступен во всех проектах, добавьте --scope user. Вариант --scope project записывает сервер в файл .mcp.json в корне проекта, общий для всей команды. Пароль в такой файл класть не стоит.

Проверка:

claude mcp list

Напротив каждого сервера будет статус: ✔ Connected, ! Needs authentication или ✘ Failed to connect. Внутри сессии Claude Code состояние серверов показывает команда /mcp.

Шаг 3. Подключите сервер к Claude Desktop

В Claude Desktop серверы описываются в файле claude_desktop_config.json. Проще всего открыть его из приложения: меню Claude → Settings… → Developer → Edit Config. Если файла нет, приложение его создаст. Лежит он здесь:

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

Добавьте блок сервера:

{
  "mcpServers": {
    "integram": {
      "command": "npx",
      "args": ["-y", "integram-mcp@0.7.124"],
      "env": {
        "INTEGRAM_URL": "https://ai2o.online",
        "INTEGRAM_EMAIL": "agent@example.com",
        "INTEGRAM_PASSWORD": "пароль-агента"
      }
    }
  }
}

Сохраните файл, полностью закройте Claude Desktop (не просто окно) и запустите снова. Новый конфиг читается только при старте. Затем нажмите «+» в поле ввода сообщения, откройте Connectors → Manage connectors и найдите там integram со списком инструментов.

Для Cursor тот же блок кладётся в .cursor/mcp.json.

Шаг 4. Выберите рабочее пространство и проверьте

У сервера integram-mcp есть необязательная переменная INTEGRAM_WORKSPACE — код рабочего пространства. Если её не задать, ничего страшного: попросите Claude показать доступные пространства и переключиться на нужное. Для этого у сервера есть встроенные инструменты list_workspaces и switch_workspace.

Первая проверка — запрос только на чтение:

Покажи список моих рабочих пространств в Интеграме. Переключись на «Тест» и перечисли таблицы.

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

Полезно знать, как устроен набор инструментов. Сразу после входа агенту доступна базовая группа: создание, чтение, изменение и поиск записей, граф связей, комментарии, массовые операции. Остальное (структура таблиц, отчёты, роли и права, история изменений с откатом, автоматизации, формы, файлы) подключается по запросу через инструмент search_tools, чтобы не перегружать модель сотнями описаний сразу. Поэтому не удивляйтесь, если в списке коннектора сначала немного инструментов.

Подтверждение опасных операций

Удаление, изменение прав, запуск коннекторов и подобные действия по умолчанию не выполняются молча. Ассистент показывает, что собирается сделать, и ждёт вашего ответа. Только после «да» операция проходит через инструмент confirm_action.

Отключить подтверждения можно переменной INTEGRAM_SKIP_HITL=true, но для рабочих данных мы этого не советуем. Изменения агента попадают в ту же историю, что и правки людей, и запись можно откатить. Только это лечение, а подтверждение — профилактика.

«Не удалось добавить сервер»: разбираем грабли

Большинство ошибок при настройке MCP-сервера сводятся к нескольким причинам. Идите по списку сверху вниз.

1. Ошибка в JSON

Самая частая причина в Claude Desktop. Типичные ошибки:

  • лишняя запятая после последнего элемента;
  • «ёлочки» или типографские кавычки вместо прямых " — так бывает, если копировать конфиг из мессенджера или текстового редактора;
  • второй сервер добавлен отдельным объектом { "mcpServers": … } рядом с первым, а не внутрь существующего mcpServers;
  • в путях Windows одиночный обратный слэш: в JSON его нужно удваивать, C:\\Users\\….

Прогоните файл через любой JSON-валидатор: это быстрее, чем гадать.

2. Клиент не находит node или npx

Терминал видит npx, а Claude Desktop нет: приложение, запущенное из меню, может не получить ваш PATH. В логах это выглядит как ENOENT или «command not found». Что помогает:

  • указать в command полный путь к npx (узнать его можно командой which npx на macOS или where npx на Windows);
  • на Windows проверить, что npm установлен глобально: должна существовать папка %APPDATA%\npm. Официальная документация MCP советует в противном случае выполнить npm install -g npm;
  • если в логе ошибка с ${APPDATA} в пути, добавить в блок env сервера переменную APPDATA с развёрнутым путём, например C:\\Users\\имя\\AppData\\Roaming\\. Этот случай тоже описан в документации MCP.

3. Сервер запускается, но не может войти

Неверный INTEGRAM_URL, опечатка в email или пароле, у пользователя нет доступа к пространству. INTEGRAM_EMAIL и INTEGRAM_PASSWORD обязательны. Если INTEGRAM_URL не задан, сервер идёт на http://localhost:8081, и для облака это гарантированная ошибка. Проверьте, что с этими логином и паролем можно войти в Интеграм через браузер.

4. Забыли перезапустить клиент

Claude Desktop перечитывает конфиг только при полном перезапуске. Закрытое окно не считается: приложение должно завершиться целиком.

5. Прокси и корпоративная сеть

npx должен скачать пакет из реестра npm, а сервер — достучаться до вашего Интеграма. За корпоративным прокси сервер integram-mcp учитывает переменные HTTPS_PROXY и HTTP_PROXY. Если Интеграм развёрнут локально, добавьте его адрес в NO_PROXY, иначе запросы к нему уйдут в прокси. Отдельно настройте прокси для самого npm, если пакет не скачивается.

6. Сервер долго стартует

При первом запуске npx скачивает пакет, и на медленной сети клиент может не дождаться ответа. Запустите команду из конфига вручную в терминале: так пакет попадёт в кэш, а вы увидите ошибку, если она есть. Для Claude Code время ожидания старта задаётся переменной MCP_TIMEOUT, например MCP_TIMEOUT=10000 claude даёт серверу 10 секунд.

Где смотреть логи

  • Claude Desktop: папка ~/Library/Logs/Claude на macOS или %APPDATA%\Claude\logs на Windows. В mcp.log пишутся общие ошибки подключения, в mcp-server-integram.log — вывод самого сервера.
  • Claude Code: claude mcp list и claude mcp get integram покажут статус и параметры. Если сервер добавлен с ошибкой, удалите его командой claude mcp remove integram и добавьте заново.

Универсальный приём для любого случая: скопируйте команду из конфига и запустите её в терминале с теми же переменными окружения. Если сервер падает там, дело не в Claude.

Безопасность: три правила

  1. Узкая роль. Широкая роль агента означает, что одна неверно понятая просьба может испортить данные. Строить и экспериментировать лучше в тестовом пространстве.
  2. Данные уходят поставщику модели. То, что агент прочитал, попадает в облачную модель. Если это недопустимо, нужен Интеграм в своём контуре и локальная модель — об этом страница «Локальный ИИ для бизнеса».
  3. Промт-инъекции. Текст внутри записей или писем может содержать «подсказки» для ИИ. Агенту с правом записи не стоит без присмотра обрабатывать непроверенный контент.

И не храните пароль агента в файлах, которые попадают в git: .mcp.json с --scope project как раз такой файл.

Что дальше

Когда Claude подключён к базе, самое интересное начинается с задач посложнее «покажи таблицы». Через те же операции агент может собрать приложение целиком: таблицы, связи, формы и отчёты. Как это выглядит, мы показали в статье базы знаний «ИИ-агент собирает приложение» и в разборе «Что умеет ИИ-агент при сборке приложения». А если MCP вам не нужен, те же операции доступны по REST API с токеном: так подключаются n8n, Make, скрипты и собственные агенты.

❡
← Все выпуски
Выпуск № 082