Integram

Integram MCP Server

MCP-сервер для Integram — даёт доступ к 808 инструментам (таблицы, документы, отчёты, автоматизации, портал, Telegram-боты, граф знаний и т.д.) из Claude Code, Claude Desktop и Cursor.

Работает с облачным Integram на ai2o.online или с локальным сервером.

Пакет: https://www.npmjs.com/package/integram-mcp

Быстрый старт

claude mcp add integram \
  -e INTEGRAM_URL=https://ai2o.online \
  -e [email protected] \
  -e INTEGRAM_PASSWORD=secret \
  -- npx -y [email protected]

Ставить ничего не нужно: npx скачает пакет сам.

Номер версии в команде обязателен. Плавающий integram-mcp@latest не годится по двум причинам. Первая: npx кэширует по строке запуска, поэтому окружение, чей кэш заполнился при старом latest, продолжает годами запускать ту сборку под тем же именем — открытая ошибка npm/rfcs#700. Второй: MCP-сервер по stdio исполняется на твоей машине с твоими правами и без песочницы, и плавающий номер означает «выполнить произвольный свежий код при каждом запуске клиента». О выходе новой версии сервер сообщит сам (см. ниже) — обновление остаётся осознанным движением.

Автообновление (для работающих в монорепозитории)

В корне монорепозитория лежит .mcp.json: сервер integram стартует через scripts/mcp-launcher.sh, и версии руками не ставятся никогда — лаунчер сам спрашивает у npm свежий номер при каждом старте сервера (коннект, reconnect, resume) и запускает npx integram-mcp@<номер>. Обход кэша здесь честный: номер входит в строку спецификации, новая версия — новая строка — гарантированная загрузка. Нет сети — стартует последняя скачанная копия.

Секьюрити-оговорка из прошлого абзаца действует и здесь, осознанно: лаунчер = «выполнять свежий код при каждом коннекте». Это выбор для машин разработчиков репозитория; для внешних пользователей — закреплённая версия из Быстрого старта.

Из репозитория (для разработки сервера)

cd mcp-server
npm install
bash setup.sh

Скрипт спросит URL, логин/пароль, клиент — и настроит всё сам. В этом режиме сервер сам подтягивает изменения: при запуске и раз в час делает git pull --ff-only, и если появились новые коммиты — доставляет зависимости и завершается, чтобы клиент поднял его заново.

Ручная настройка

Claude Code

Локальный сервер вместо облака — меняется только URL:

claude mcp add integram \
  -e INTEGRAM_URL=http://localhost:8081 \
  -e [email protected] \
  -e INTEGRAM_PASSWORD=secret \
  -- npx -y [email protected]

Удалить: claude mcp remove integram

Claude Desktop

Добавить в ~/.config/claude-desktop/claude_desktop_config.json:

{
  "mcpServers": {
    "integram": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "INTEGRAM_URL": "https://ai2o.online",
        "INTEGRAM_EMAIL": "[email protected]",
        "INTEGRAM_PASSWORD": "secret"
      }
    }
  }
}

Cursor

Добавить в .cursor/mcp.json:

{
  "mcpServers": {
    "integram": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "INTEGRAM_URL": "https://ai2o.online",
        "INTEGRAM_EMAIL": "[email protected]",
        "INTEGRAM_PASSWORD": "secret"
      }
    }
  }
}

Клон репозитория вместо пакета — "command": "node", "args": ["/absolute/path/to/mcp-server/index.js"].

Обновление

Клиент не узнаёт о новой версии сам — закреплённый в конфиге номер не меняется, — поэтому сервер сообщает об этом сам. Раз в сутки он спрашивает у реестра npm тег latest (только теги, без метаданных пакета) и, если выложено новее, подаёт сигнал по двум каналам:

• в stderr — строкой Доступна версия X (запущена Y). Это единственный поток, куда спецификация stdio-транспорта разрешает писать что угодно; в stdout нельзя ничего, кроме JSON-RPC. Клиент вправе stderr проигнорировать — поэтому канал не один;
• припиской к ответу первого вызова инструмента — единственный канал, доходящий до модели и через неё до человека. Ровно один раз за запуск процесса.

Как пакет попадает в npm: пуш в master основного репозитория → каталог зеркалится в публичный judas-priest/integram-mcp → тамошний publish.yml выкладывает по OIDC, если такого номера в реестре ещё нет, и сверяет sha256 отданного архива с исходником. Номер поднимает pre-commit. Токенов в цепочке нет, и npm publish руками не работает: на npm включено «require 2FA and disallow bypass 2fa tokens», выложить может только этот воркфлоу. У каждой версии, вышедшей этим путём, на странице пакета стоит отметка provenance.

Обновиться — заменить номер версии в конфиге MCP и перезапустить клиент:

claude mcp remove integram
claude mcp add integram -e INTEGRAM_URL=... -e INTEGRAM_EMAIL=... -e INTEGRAM_PASSWORD=... \
  -- npx -y integram-mcp@НОВАЯ_ВЕРСИЯ

Проверка не блокирует запуск, молчит без сети и глушится переменными NO_UPDATE_NOTIFIER=1 (общепринятое соглашение) или INTEGRAM_MCP_NO_UPDATE_CHECK=1. Ответ реестра кэшируется на сутки в системном временном каталоге. Бета-версии не предлагаются тому, кто сидит на стабильной.

Чего здесь намеренно нет: пакета update-notifier — он печатает в stdout и только при TTY, то есть под stdio-транспортом не сработает и сломает протокол; и протокольного notifications/message — он объявлен устаревшим в версии протокола 2026-07-28, а отправка до initialize ломает строгие клиенты.

Уведомления

• On startup the server checks unread notifications across workspaces and appends a summary to the first tool response.

Переменные окружения

Как это работает

1. При запуске логинится в Integram
2. Если воркспейс указан — загружает инструменты сразу. Если нет — ждёт switch_workspace
3. Активирует core инструменты (CRUD, поиск, граф) + 4 встроенных
4. Остальные инструменты подключаются по запросу через search_tools
5. Вызовы проксируются на бэкенд с JWT-авторизацией
6. JWT обновляется автоматически
7. Раз в сутки сверяет свою версию с тегом latest в npm — см. «Обновление»

Встроенные инструменты

Всегда доступны, работают без воркспейса:

В воркспейсе (группа core, загружается по умолчанию) есть report_platform_issue — отправить отчёт о проблеме платформы мейнтейнеру: после необъяснимого отказа инструмента, нескольких неудачных попыток подряд, осознанной ошибки агента или прямой просьбы пользователя. LLM составляет черновик из контекста отказа и показывает пользователю, отправка — после подтверждения (HITL); секреты серверно вырезаются; отчёты дедуплицируются — одна проблема = одна задача со счётчиком вхождений. Ответ содержит номер issue.

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

Удаление, изменение прав, запуск коннекторов и т.д. по умолчанию требуют подтверждения — LLM спрашивает пользователя и вызывает confirm_action(approved=true/false).

INTEGRAM_SKIP_HITL=true отключает подтверждения.

Группы инструментов

Core активна сразу (21 tools). Остальные — через search_tools.