AIKraft Agents

chigwell/telegram-mcp

Сервер Telegram MCP на базе Telethon для чтения чатов, управления группами и отправки/изменения сообщений, медиа, контактов и настроек.

MCP⭐ 1 995Pythonпоследний релиз: v3.3.4
Открыть на GitHub ↗

Что это за инструмент

Telegram MCP Server — это серверная надстройка на базе Telethon, которая позволяет MCP-совместимым клиентам (например, Claude или Cursor) управлять аккаунтом Telegram, читать чаты и отправлять сообщения.

Зачем нужен

Инструмент решает задачу интеграции возможностей Telegram с AI-агентами через стандарт Model Context Protocol. Он полезен для автоматизации рутинных операций в мессенджере, таких как анализ истории переписки, модерация групп и массовая рассылка, непосредственно из интерфейса AI-ассистента.

Что можно реализовать

  • Анализ истории чатов и отправка ответов от имени пользователя через Claude Desktop
  • Автоматическая модерация групп: управление администраторами, баны, настройки slow mode
  • Мониторинг и обработка входящих сообщений с возможностью ответа и пересылки
  • Управление контактами: поиск, добавление, блокировка и экспорт/импорт списков
  • Работа с медиа: отправка файлов, голосовых сообщений, стикеров и GIF-анимации

Ключевые возможности

  • Более 80 инструментов MCP, охватывающих аккаунты, чаты, сообщения, контакты, медиа и профили
  • Поддержка мультиаккаунтной работы с маршрутизацией запросов по меткам
  • Возможность запуска в режиме «только чтение» (read-only) для ограничения прав на запись
  • Готовая поддержка Docker и валидации конфигурации через CI/CD
  • Санитизация пользовательского контента и возврат результатов в структурированном JSON

👤 Кому подойдёт: разработчики, использующие MCP-клиенты (Claude, Cursor), и технические специалисты, занимающиеся автоматизацией процессов в Telegram

Релизы

v3.3.4patch
🕐 6 дн назад · релиз на GitHub ↗

Исправлена работа ленты событий на Windows для версий Python ниже 3.13 и обновлены зависимости безопасности.

  • Fixed: Исправлено открытие ленты событий на Windows для версий Python до 3.13.
  • Fixed: Обновлены библиотеки pypdf, pillow, certifi и pyasn1 до исправленных версий.
v3.3.3patch
🕐 7 дн назад · релиз на GitHub ↗

Исправлена работа с rich-post: ссылки и встроенные медиа теперь доступны через @axisrow.

  • Fixed: Исправлена обработка rich-post: ссылки и встроенные медиа теперь корректно доступны через @axisrow.
v3.3.2patch
🕐 9 дн назад · релиз на GitHub ↗

Обновление документации: добавлены описания параметров chat_id и limit для функции get_history.

  • Added: Добавлено описание параметров chat_id и limit в документацию функции get_history.
  • Added: Первый вклад в проект внесён пользователем @mmporong.
v3.3.1minor
🕐 10 дн назад · релиз на GitHub ↗

Обновлён форматирование подписей к файлам и альбомам в Telegram через parse_mode и кастомные эмодзи.

  • Added: Добавлена поддержка форматирования подписей send_file и send_album с использованием parse_mode и кастомных эмодзи.
v3.2.98minor
🕐 13 дн назад · релиз на GitHub ↗

Добавлена глобальная пагинация поиска Telegram и исправлена отправка медиафайлов с корректными метаданными.

  • Added: Реализована глобальная пагинация через курсор в поиске Telegram.
  • Fixed: Функция send_file теперь корректно возвращает реальные размеры и длительность видео.
  • Fixed: Исправлен поиск GIF: get_gif_search возвращает документы, совместимые с send_gif.
v3.2.97patch
🕐 16 дн назад · релиз на GitHub ↗

Исправлено различие страниц глобального поиска и корректный вывод кириллицы/эмодзи через json.dumps.

  • Fixed: Исправлена логика, чтобы страницы глобального поиска (search_global) были корректно различимы.
  • Fixed: Устранена проблема с выводом кириллицы и эмодзи в инструментах, использующих json.dumps.
v3.2.94patch
🕐 16 дн назад · релиз на GitHub ↗

Исправления в работе с закреплёнными сообщениями, медиа, группами, транскрипцией, сессиями и санитизацией текста.

  • Fixed: get_pinned_messages теперь корректно возвращает все закреплённые сообщения.
  • Fixed: Улучшена обработка медиа: формат изображений определяется по байтам, нечитаемые файлы пропускаются.
  • Fixed: Добавлена поддержка базовых групп в инструментах получения администраторов и заблокированных пользователей.
  • Fixed: При недоступности рабочей директории для транскрипции используется кэш пользователя.
  • Fixed: Исправлена работа раннера: пропущена пресетная сессия, которая не вошла в систему.
  • Fixed: Сохранены разделители, необходимые для корректного отображения эмодзи и слов.
v3.2.93patch
🕐 16 дн назад · релиз на GitHub ↗

Исправлена ошибка вывода None для пользователей без фамилии и устранены предупреждения о депрекейте тестов.

  • Fixed: Исправлен баг, из-за которого у пользователей без фамилии выводилось значение None
  • Deprecated: Устранены предупреждения о депрекейте в библиотеках pythonjsonlogger и pytest-asyncio
v3.2.90minor
🕐 18 дн назад · релиз на GitHub ↗

Добавлен инструмент для получения приглашений в папки, улучшена обработка ошибок и отправка файлов.

  • Added: Добавлен инструмент get_chatlist_invite для чтения списков приглашений в папки.
  • Added: Функция send_file теперь поддерживает отправку файлов в формате документов.
  • Fixed: Исправлена ошибка: теперь ошибки изменения сообщений возвращаются корректно, а не как сбой.
  • Fixed: В сообщениях об ошибках Telegram RPC теперь указывается их имя.
v3.2.88minor
🕐 19 дн назад · релиз на GitHub ↗

В версии 3.2.88 добавлен инструмент upgrade_group_to_supergroup для преобразования групп в супергруппы.

  • Added: Добавлен инструмент upgrade_group_to_supergroup для преобразования обычных групп в супергруппы.
v3.2.86minor
🕐 19 дн назад · релиз на GitHub ↗

Добавлена поддержка индикаторов набора текста с ограничением в форумах Telegram.

  • Added: Введены ограниченные индикаторы набора текста (typing indicators) с поддержкой форумов.
v3.2.85patch
🕐 20 дн назад · релиз на GitHub ↗

Исправления в Telegram MCP: повторный вход, удаление сообщений, проверка списка разрешённых чатов и настройки приватности.

  • Fixed: Исправлен повторный вход: результат неудачной попытки теперь передаётся ожидающим вызовам.
  • Fixed: Удаление сообщений: теперь удаляются только сообщения из указанного чата.
  • Fixed: Список разрешённых чатов: добавлена проверка contact_id и group_id, скрыты запрещённые чаты.
  • Fixed: Настройки приватности: исправлено слияние исключений, чтобы не открывать доступ всем.
v3.2.83patch
🕐 20 дн назад · релиз на GitHub ↗

Исправления в чатах, санитизации данных, аккаунтах, конфигурации, псевдонимах, фото и эмодзи, а также обновление линтера.

  • Fixed: Исправлено формирование заголовков чатов по имени и фамилии, а также декодирование и санитизация байтовых полей.
  • Fixed: Теперь дефисы в метках аккаунтов заменяются на подчеркивания, а для файла псевдонимов создаются родительские директории.
  • Fixed: Улучшена читаемость ошибок конфигурации при отсутствии API-идентификатора и хеша, а также исправлена логика работы с веб-превью фото.
  • Fixed: Запрещено использование неэмодзи символов (например, №, ™) в качестве замены для кастомных эмодзи.
  • Обновлен линтер flake8 для соответствия black, очищен backlog ошибок E501 и F84x.
v3.2.82patch
🕐 21 дн назад · релиз на GitHub ↗

Исправлена ошибка, приводившая к созданию лишних вложенных папок загрузок при указанной корневой директории.

  • Fixed: Устранена проблема с созданием избычных вложенных папок в директории загрузок.
v3.2.81patch
🕐 22 дн назад · релиз на GitHub ↗

В версии v3.2.81 добавлена поддержка отображения названий форумных тем при чтении сообщений.

  • Added: Добавлена возможность передачи информации о названии форума и заголовках тем в сообщениях.
v3.2.80patch
🕐 24 дн назад · релиз на GitHub ↗

Исправлена сериализация переподключений при одновременных вызовах инструментов.

  • Fixed: Исправлена сериализация переподключений во время одновременных вызовов инструментов.
v3.2.79minor
🕐 24 дн назад · релиз на GitHub ↗

В Telegram MCP добавлена поддержка пользовательских эмодзи при отправке, ответах и редактировании текстовых сообщений.

  • Added: Добавлена возможность использования пользовательских эмодзи (custom_emojis) в функциях отправки, ответа и редактирования сообщений.
  • Added: Поддержка эмодзи доступна для plain text сообщений.
v3.2.76patch
🕐 25 дн назад · релиз на GitHub ↗

Исправлено чтение и запись файла .env с корректной кодировкой UTF-8.

  • Fixed: Исправлено чтение и запись файла .env с использованием кодировки UTF-8.
v3.2.75minor
🕐 27 дн назад · релиз на GitHub ↗

Добавлена возможность голосовать в существующих опросах Telegram через MCP.

  • Added: Реализована функция голосования в уже созданных опросах Telegram.
v3.2.73patch
🕐 28 дн назад · релиз на GitHub ↗

Исправлена зависимость: добавлена библиотека pypdf в файл requirements.txt.

  • Fixed: Добавлена библиотека pypdf в список зависимостей requirements.txt.
v3.2.72minor
🕐 28 дн назад · релиз на GitHub ↗

Исправлена работа с PID на Windows, добавлен просмотр кастомных эмодзи и поддержка протокола MCP 2026-07-28.

  • Fixed: Исправлено чтение PID процесса-хостера при отказе в Windows.
  • Added: Добавлен просмотр и предпросмотр пакетов пользовательских эмодзи.
  • Added: Реализована поддержка протокола MCP 2026-07-28 и согласования транспорта.
v3.2.71patch
🕐 29 дн назад · релиз на GitHub ↗

Исправлено получение истории сообщений: теперь темы форумов загружаются с сервера через reply_to.

  • Fixed: Исправлена загрузка истории: темы форумов теперь запрашиваются с сервера через поле reply_to.
  • Added: Первый вклад в проект внесён пользователем @Royedc4.
v3.2.70patch
🕐 1 мес назад · релиз на GitHub ↗

Исправлена ошибка, из-за которой функция приглашения в супергруппы возвращала 0 пользователей.

  • Fixed: Исправлена ошибка в логике invite_to_group, которая некорректно сообщала о нуле приглашённых пользователей в супергруппах.
v3.2.67patch
🕐 1 мес назад · релиз на GitHub ↗

Исправлена обработка аргументов инструментов, принимающих null по умолчанию.

  • Fixed: Исправлена работа инструментов: теперь корректно принимаются null для аргументов, по умолчанию равных None.
v3.2.66patch
🕐 1 мес назад · релиз на GitHub ↗

Исправлена ошибка, из-за которой export_unread_messages выходил за пределы разрешённых корневых директорий.

  • Fixed: Исправлена ошибка: параметр export_unread_messages теперь корректно остаётся в пределах разрешённых корневых директорий.
v3.2.65minor
🕐 1 мес назад · релиз на GitHub ↗

В Telegram MCP v3.2.65 добавлена поддержка лимитов, снимков и безопасного обновления приватных папок.

  • Added: Пользователи теперь могут управлять лимитами для папок.
  • Added: Добавлена возможность создания снимков (snapshots) состояния папок.
  • Added: Реализован безопасный механизм обновления приватных папок.
v3.2.63minor
🕐 1 мес назад · релиз на GitHub ↗

Добавлена проверка прав участника в группах, улучшена работа с корнями и исправлен цикл авторизации при переподключении.

  • Added: Добавлена функция get_member_admin_status для получения роли и прав конкретного участника в группах.
  • Added: Реализована опция server-only roots и закреплены тесты на побег через символические ссылки.
  • Fixed: Исправлена ошибка: теперь интерактивный вход не запускается при переподключении.
  • Added: Добавлена опциональная проверка TELEGRAM_EXPECTED_USERNAME для дополнительной безопасности.
v3.2.62minor
🕐 1 мес назад · релиз на GitHub ↗

Добавлен манифест MCPB для установки Claude Desktop в один клик.

  • Added: Добавлен манифест MCPB, позволяющий установить Claude Desktop в один клик.
v3.2.60minor
🕐 1 мес назад · релиз на GitHub ↗

В инструментах list, search и context теперь возвращается полная запись сообщения.

  • Added: Инструменты list, search и context стали возвращать полную запись сообщения.
v3.2.59minor
🕐 1 мес назад · релиз на GitHub ↗

Добавлены движки транскрипции faster-whisper и OpenAI-compatible.

  • Added: Появились движки транскрипции faster-whisper и OpenAI-compatible.