| name | telegram-workflow |
| description | Правила и контекст работы с личным Telegram-аккаунтом пользователя через MCP-сервер claudegram. Загружается, когда пользователь просит читать чаты, искать сообщения, отвечать кому-то в Telegram, делать сводку непрочитанных, управлять диалогами, создавать чаты/каналы, модерировать группу, скачивать медиа, управлять контактами, или вообще обращается к Telegram-аккаунту. |
| when_to_use | Активируется на: 'что у меня в Telegram', 'найди в чатах', 'напиши/отправь в тг', 'удали сообщение', 'забань', 'создай группу/канал', 'переименуй чат', 'кикни', 'admin', 'статистика канала', 'опрос', 'голосуй', 'скачай вложение', 'контакты'. |
| disable-user-invocation | true |
Работа с Telegram через claudegram
MCP-сервер claudegram даёт доступ к личному аккаунту пользователя
через MTProto (не бот). 58 типизированных tools, разбитых по категориям.
Базовые принципы безопасности
- Никогда не отправляй сообщения без явного подтверждения. Намерение «составить черновик» ≠ намерение отправить. Покажи проект текста и жди слов вроде «отправь / шли / да».
delete_message(revoke=True) — необратимо. Дефолт False (только у себя). Hook guard-delete требует подтверждения. Не передавай True без явного запроса юзера.- Не помечай прочитанным автоматически.
mark_read — только по явной просьбе. Иначе пользователь потеряет визуальные индикаторы непрочитанного.
- Деструктивные операции на чатах:
kick_participant, ban_participant, delete_dialog, leave_chat, terminate_authorization, block_user — всегда показывай action + entity и жди "да".
- Markdown в
send_message/edit_message. Если в тексте есть *, _, [, ], ~, \``, и это **не** разметка — передай parse_mode="none"`, иначе Telegram упадёт с ParseMode-error.
- Сессия — это пароль. Файл
*.session в ${CLAUDE_PLUGIN_DATA} даёт полный доступ к аккаунту. Никогда не предлагай пересылать его, копировать в чат, коммитить.
invoke_raw — крайний инструмент. Используй только если нет high-level tool. Можешь случайно изменить состояние аккаунта или нарваться на flood-wait.
Каталог инструментов
Все имена под префиксом mcp__plugin_claudegram_claudegram__. Сгруппированы по модулям.
Identity / Account (server/tools/identity/account.py)
| Tool | Назначение |
|---|
get_me | Кто я залогинен |
get_authorizations | Список активных сессий аккаунта (другие устройства) |
terminate_authorization | Завершить чужую сессию (по hash) |
update_profile | Изменить имя/фамилию/био |
set_online | Online/offline статус |
Messaging (server/tools/messaging/{messages,history,pins,reactions}.py)
| Tool | Назначение |
|---|
send_message | Отправить (parse_mode, reply_to, silent, link_preview, schedule_unix) |
edit_message | Отредактировать своё |
delete_message | Удалить (revoke=False default) |
forward_message | Переслать (silent, drop_author) |
get_history | Последние N (offset_id, min_id, from_user, reverse) |
search_messages | Поиск по тексту (chat, from_user) |
mark_read | Прочитано (max_id, clear_mentions) |
pin_message | Закрепить (notify, pm_oneside) |
unpin_message | Открепить одно или все |
react_message | Поставить эмодзи-реакцию ("" чтобы снять) |
send_dice | 🎲/🎯/🏀/⚽/🎰/🎳 |
Dialogs (server/tools/dialogs/{list_,folders,notify}.py)
| Tool | Назначение |
|---|
list_chats | Список диалогов (archived, only_unread, ignore_pinned) |
get_drafts | Несохранённые черновики |
archive_dialog / unarchive_dialog | Архив |
delete_dialog | Покинуть/удалить |
mute_dialog / unmute_dialog | Уведомления |
Peers (server/tools/peers/{lookup,users,contacts}.py)
| Tool | Назначение |
|---|
get_chat_info | Метаданные entity |
resolve_username | @username → entity + id |
get_participants | Участники (search, filter_admin/kicked/banned) |
get_profile_photos | Метаданные аватарок |
block_user / unblock_user | (Раз)блокировать |
get_common_chats | Общие чаты с юзером |
Chats (server/tools/chats/{create,settings,members,invites,admin}.py)
| Tool | Назначение |
|---|
create_group | Обычная группа с участниками |
create_channel | Канал (broadcast=True) или супергруппа (megagroup=True) |
edit_chat_title | Переименовать |
edit_chat_about | Описание |
join_chat / leave_chat | Войти / выйти |
kick_participant | Кик (можно вернуться) |
ban_participant / unban_participant | Бан навсегда |
promote_admin (с правами) / demote_admin | Админ |
get_admin_log | Журнал действий админов |
get_stats | Статистика канала (только админу) |
Media (server/tools/media/{files,download,attachments,stickers}.py)
| Tool | Назначение |
|---|
download_media | Скачать вложение из сообщения |
download_profile_photo | Скачать аватарку |
send_file | Отправить файл (force_document, voice_note, video_note) |
send_album | 2-10 фото/видео одной группой |
send_location | Координаты (live_period для live-локации) |
send_contact | Визитка |
get_media_info | Метаданные медиа без скачивания |
Contacts (server/tools/peers/contacts.py)
| Tool | Назначение |
|---|
get_contacts | Все контакты |
add_contact | Добавить (с phone_privacy_exception) |
delete_contact | Удалить |
search_global | Глобальный поиск юзеров/чатов/каналов |
Content / Polls (server/tools/content/polls.py)
| Tool | Назначение |
|---|
send_poll | Опрос (anonymous, multiple_choice, quiz + correct_option_index) |
vote_poll | Проголосовать (option_indices) |
Advanced / Raw API (server/tools/advanced/raw.py)
| Tool | Назначение |
|---|
invoke_raw | Вызов любого MTProto-метода через telethon.tl.functions.<...> |
get_input_peer | Получить InputPeer для использования в invoke_raw |
Идентификация чатов
- Параметр
chat принимает: целочисленный id (напр. -1001234567890),
@username, или просто username без @.
- Если пользователь говорит «напиши Пете» — сначала найди Петю через
search_global или resolve_username. Не угадывай id.
- Перед действиями над незнакомым чатом покажи
get_chat_info —
пусть пользователь подтвердит, что это правильный собеседник.
- В групповых чатах для
forward_message/pin_message используй полный
signed id (-100<chan_id> для супергрупп). dialog_brief.peer_id
возвращает уже правильный формат.
Типичные сценарии
«Что пропустил?» → list_chats(only_unread=true) → для каждого
get_history(limit=unread_count) → сгруппированная сводка. Не зови mark_read.
«Найди про X» → если упомянут чат — resolve_username → search_messages(query, chat). Иначе глобальный поиск или search_global.
«Ответь Y кому-то» → найди чат → составь черновик → покажи + получатель → жди «отправляй» → send_message(reply_to=...) если ответ на конкретное сообщение.
«Скачай это видео» → get_history найди message_id → get_media_info для проверки → download_media(chat, message_id, download_dir).
«Создай группу с Васей и Петей» → resolve_username для каждого → собери список id → create_group(title, users) → жди подтверждения title'а перед созданием.
«Кто админы канала?» → get_participants(chat, filter_admin=True).
«Замьють чат до утра» → mute_dialog(chat, mute_until_unix=<завтра 9:00 UTC>). Перед — спроси подтверждение времени.
«Переименуй чат в …» → get_chat_info показать текущее название → edit_chat_title(chat, new_title) после подтверждения.
«Лайкни последнее» → get_history(chat, limit=1) → react_message(chat, message_id, emoji='👍').
«Отправь голосовое» → send_file(chat, '/path/to/voice.ogg', voice_note=True). Если файл не .ogg — сначала convert через ffmpeg (предложи команду юзеру).
«Сделай опрос: «Куда обедать?» с вариантами «Sushi/Pizza/Burger»» → send_poll(chat, question, options, anonymous=True) после подтверждения.
«Что в админ-логе?» → get_admin_log(chat, limit=50).
Пагинация и лимиты
get_history / search_messages / get_participants / get_admin_log: limit обычно 1-200. Для больших объёмов — несколько вызовов с offset_id (для сообщений) или продвигайся по страницам.- Не запрашивай больше, чем нужно — каждый вызов = запрос к Telegram под лимитом FloodWait.
Ошибки
- «Telegram-сессия не авторизована» →
claudegram-auth (через ! claudegram-auth в Claude или uv run claudegram-auth в shell).
FloodWaitError: A wait of N seconds is required → подожди ровно N секунд (Telethon бросит FloodWaitError), не ретрай в цикле.UsernameNotOccupiedError → нет такого @username. Перепроверь.ChatAdminRequiredError → нужны права админа для операции (get_stats, kick, promote и т.п.).UserNotParticipantError → юзер не в этом чате (для kick/promote).MessageNotModifiedError при edit_message → новый текст идентичен старому.
Channel-режим
Если плагин запущен с enable_channel_mode=1 и --channels, входящие
сообщения от allowlist'ed юзеров приходят в сессию как <channel source="claudegram">
теги. См. отдельный skill tg-channel-incoming для правил их обработки.
