Claudegram

TL;DR

Claudegram — production-grade плагин Claude Code, превращающий личный Telegram в управляемый AI-инструмент:

• MTProto, не Bot API — видит всю переписку, истории, поиск, медиа, статистику.

• 120 типизированных MCP-tools через FastMCP, разбиты на 9 доменов; покрыты safe_tool middleware с FloodWait/RPCError handling и санитизацией секретов.

• Channel-режим: входящие сообщения push-ятся в активную сессию Claude как <channel> теги с permission relay (yes/no через <id>).

• 4-слойная safety net: PreToolUse hooks (guard-delete, guard-destructive, guard-confirm) + disable-model-invocation для отправки сообщений + sensitive userConfig в системный keychain.

• Skills + Prompts: tg-digest, tg-search, tg-history, tg-send, tg-reply, telegram-workflow — готовые сценарии для рекрутерского тестового запуска.

Полный список возможностей — в таблице ниже.

Why this project

• Реальный production-ready MCP-сервер: типизированные tools, structured output, prompt templates, completions, resource templates.

• Безопасность спроектирована up-front: модель угроз, hook-гейты, allowlist, sanitize в логах. См. SECURITY.md.

• Чистая архитектура: 75 модулей, ~6.3k строк server-кода, ~900 строк тестов, ruff + mypy, CI на GitHub Actions, Codecov, CodeQL.

• Каждое решение объяснено docstring'ом и CHANGELOG'ом, без «магии».

Quick start

git clone https://github.com/sanjar-x/claudegram.git && cd claudegram
uv sync
cp .env.example .env  # вставь api_id/api_hash/phone с https://my.telegram.org
uv run claudegram-auth
# затем в Claude Code: /plugin add . && /plugin install claudegram

Подробнее — в разделе «Установка» ниже.

В отличие от Bot API, Claudegram видит всю историю, все чаты и поддерживает поиск. Архитектура и компоненты выровнены под официальную спеку Claude Code Plugins.

Возможности

Структура

Claudegram/
├── .claude-plugin/
│   └── plugin.json                  # манифест с userConfig (api_id/hash/phone/2fa)
├── .mcp.json                        # MCP stdio-сервер, env через ${user_config.*}
├── hooks/
│   ├── hooks.json                   # SessionStart auth-check, PreToolUse delete-guard
│   └── scripts/
│       ├── check-auth.sh
│       └── guard-delete.sh
├── skills/                          # каждая команда — отдельный каталог с SKILL.md
│   ├── telegram-workflow/SKILL.md   # фоновые правила (user-invocable: false)
│   ├── tg-channel-incoming/SKILL.md # обработка <channel source="claudegram"> тегов
│   ├── tg-digest/SKILL.md           # /claudegram:tg-digest [N]
│   ├── tg-search/SKILL.md           # /claudegram:tg-search <запрос> [@chat]
│   ├── tg-history/SKILL.md          # /claudegram:tg-history <@chat> [limit]
│   ├── tg-send/SKILL.md             # /claudegram:tg-send <@chat> <текст>  (disable-model-invocation)
│   └── tg-reply/SKILL.md            # /claudegram:tg-reply <@chat> <id> <текст>
├── bin/
│   └── claudegram-auth              # шелл-обёртка над server.auth
├── server/                          # Python MCP-сервер (FastMCP + Telethon)
│   ├── __init__.py
│   ├── config.py                    # plugin-mode + standalone-mode env loading
│   ├── auth.py                      # одноразовый интерактивный логин
│   ├── client.py                    # singleton TelegramClient
│   ├── formatters.py                # сериализация в JSON
│   ├── channel.py                   # channel-режим: push + permission relay
│   ├── main.py                      # FastMCP entry + custom stdio runner с experimental caps
│   └── tools/                       # 92 tools в 8 доменах с подпакетами
│       ├── __init__.py              # register_all(mcp) — диспатчит по доменам
│       ├── _common.py               # shared utils (ParseMode, normalize_chat, clamp, to_jsonable)
│       ├── identity/                # account, sessions
│       │   ├── account.py           # get_me, update_profile, set_online, update_username, get_full_user
│       │   └── sessions.py          # get_authorizations, terminate_authorization
│       ├── peers/                   # discovery + метаданные сущностей
│       │   ├── lookup.py            # resolve_username, get_chat_info, search_global, get_top_peers, get_input_peer
│       │   ├── users.py             # get_profile_photos, download_profile_photo, get_common_chats
│       │   └── contacts.py          # CRUD + block/unblock + import + get_blocked
│       ├── messaging/               # send/edit/history/pins/reactions
│       │   ├── messages.py          # send/edit/delete/forward
│       │   ├── history.py           # get_history (+filter_type), search_messages
│       │   ├── pins.py              # pin_message, unpin_message
│       │   └── reactions.py         # react_message
│       ├── dialogs/                 # список и состояния диалогов
│       │   ├── list_.py             # list_chats, get_drafts
│       │   ├── folders.py           # archive/unarchive/pin_dialog
│       │   └── notify.py            # mark_read, mute, unmute, delete_dialog
│       ├── chats/                   # управление группами/каналами
│       │   ├── create.py            # create_group, create_channel
│       │   ├── settings.py          # title/about/photo/forum_mode
│       │   ├── members.py           # participants, kick, ban, unban, restrict, promote, demote
│       │   ├── invites.py           # join, leave, export_invite
│       │   └── admin.py             # admin_log, stats
│       ├── media/                   # файлы и attachments
│       │   ├── files.py             # send_file, send_album
│       │   ├── download.py          # download_media, get_media_info
│       │   ├── attachments.py       # send_location, send_contact, send_dice
│       │   └── stickers.py          # все sticker-операции
│       ├── content/                 # контент-фичи
│       │   ├── polls.py             # send/vote/results
│       │   ├── stories.py           # all stories operations
│       │   └── forums.py            # forum-topics
│       └── advanced/
│           └── raw.py               # invoke_raw — ANY MTProto method
├── pyproject.toml + uv.lock         # uv-проект
├── .env.example                     # для standalone-режима
├── .gitignore                       # игнорит .env, *.session, .venv, кеши
└── README.md

Стек

• Python 3.14, uv

• Telethon 1.43+ — MTProto-клиент

• mcp[cli] 1.x — официальный SDK MCP

Установка

1. Получить API-креденшелы

1. Открой https://my.telegram.org → API development tools.

2. Создай приложение (любые App title / Short name).

3. Скопируй api_id и api_hash.

2. Установить зависимости (uv создаст .venv/)

cd ~/Desktop/Claudegram
uv sync

3. Подключить плагин в Claude Code

Самый быстрый способ для разработки — --plugin-dir (грузит как сессионный плагин, без установки):

claude --plugin-dir ~/Desktop/Claudegram

Постоянная установка через локальный marketplace (marketplace.json уже включён в .claude-plugin/):

/plugin marketplace add ~/Desktop/Claudegram
/plugin install claudegram@claudegram-local

claudegram-local — имя локального marketplace из .claude-plugin/marketplace.json.

При первом включении Claude Code откроет промпт и попросит ввести tg_api_id, tg_api_hash, tg_phone (поля userConfig из манифеста). Сенситивные значения уйдут в системный keychain, не в settings.json.

4. Авторизоваться (один раз)

⚠️ Важно: bin/claudegram-auth попадает в PATH только Bash tool внутри Claude Code, не в обычный shell хоста (это ограничение Claude Code, см. plugins-reference).

Вариант A (рекомендуемый, из активной Claude-сессии):

! claudegram-auth

Префикс ! запускает команду в shell сессии, и тогда bin/claudegram-auth из плагина уже в PATH.

Вариант B (из обычного терминала, standalone):

cd ~/Desktop/Claudegram
uv run python -m server.auth
# или
uv run claudegram-auth     # после `uv sync` появляется console-script

В обоих случаях — введи код из Telegram. Файл сессии создастся:

• Plugin-mode: ~/.claude/plugins/data/claudegram-claudegram-local/claudegram.session (переменная ${CLAUDE_PLUGIN_DATA}) — не теряется при апдейте плагина.

• Standalone: в корне проекта ~/Desktop/Claudegram/claudegram.session.

5. Проверить

/mcp                 # должен появиться сервер "claudegram"
/reload-plugins      # после правок без рестарта
/hooks               # увидишь SessionStart + PreToolUse гейт

Использование

Slash-skills (тип /claudegram:<skill>)

• /claudegram:tg-digest [N] — сводка непрочитанных по N чатам.

• /claudegram:tg-search <запрос> [@chat] — поиск.

• /claudegram:tg-history <@chat> [N] — последние N сообщений чата.

• /claudegram:tg-send <@chat> <текст> — отправка с подтверждением. Только пользователь вызывает (disable-model-invocation: true).

• /claudegram:tg-reply <@chat> <id> <текст> — ответ на конкретное сообщение. Только пользователь.

Авто-активация

Skill telegram-workflow (user-invocable: false) подгружается, когда ты пишешь "что у меня в Telegram?", "найди в чатах", "напиши Пете". Claude по описанию выбирает правильный MCP-tool и следует safety-правилам из этого skill.

Прямые MCP-инструменты (58 шт)

Полный namespace: mcp__plugin_claudegram_claudegram__<tool>. Wildcard для permission-rule: mcp__plugin_claudegram_claudegram__*.

Полный каталог с описаниями и сигнатурами — в skill'е telegram-workflow/SKILL.md. Краткая сводка по категориям:

• Account (5): get_me, get_authorizations, terminate_authorization, update_profile, set_online

• Messages (11): send_message, edit_message, delete_message, forward_message, get_history, search_messages, mark_read, pin_message, unpin_message, react_message, send_dice

• Dialogs (7): list_chats, get_drafts, archive_dialog, unarchive_dialog, delete_dialog, mute_dialog, unmute_dialog

• Users (7): get_chat_info, resolve_username, get_participants, get_profile_photos, block_user, unblock_user, get_common_chats

• Chats (12): create_group, create_channel, 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 (7): download_media, download_profile_photo, send_file, send_album, send_location, send_contact, get_media_info

• Contacts (4): get_contacts, add_contact, delete_contact, search_global

• Polls (2): send_poll, vote_poll

• Raw API (2): invoke_raw, get_input_peer — escape hatch для любого MTProto-метода через telethon.tl.functions.<module>.<MethodNameRequest>. Покрывает Stories, Payments, Stickers, Channels admin, Folders, Themes — всё, что не обёрнуто high-level API.

Как работает безопасность

• .env и *.session в .gitignore.

• Sensitive userConfig (api_hash, phone, 2FA) уходят в системный keychain (или ~/.claude/.credentials.json), не в settings.json.

• *.session лежит в ${CLAUDE_PLUGIN_DATA} — не утекает с апдейтом, но даёт полный доступ к аккаунту, храни как пароль.

• PreToolUse-хук на delete_message принудительно спрашивает, если revoke=true.

• Skill telegram-workflow обязывает Claude получать явное подтверждение перед send_message/mark_read/delete_message.

• Telegram может посчитать активность подозрительной → возможна блокировка. Для экспериментов используй отдельный аккаунт.

Standalone-режим (без плагина)

Можно запустить MCP-сервер вне Claude Code:

cp .env.example .env
$EDITOR .env       # заполни TG_API_ID/HASH/PHONE
uv run python -m server.auth        # логин, .session ляжет в корень
uv run python -m server.main        # MCP stdio-сервер

server/config.py сначала читает TG_* (или .env), затем — CLAUDE_PLUGIN_OPTION_TG_*, которые экспортируются плагином. Один и тот же код работает в обоих режимах.

Расширение

• Новый MCP-tool → функция в server/main.py с @mcp.tool(). FastMCP сам сгенерирует JSON-схему по type-hints + docstring.

• Новый skill → каталог skills/<name>/ с SKILL.md. Frontmatter: name, description, опционально argument-hint, arguments, allowed-tools, disable-model-invocation, paths, model, effort.

• Новый hook → редактируй hooks/hooks.json. Доступные события см. hooks reference.

• Бинарь → положи в bin/<name> + chmod +x. Автоматически попадёт в PATH.

После любых изменений: /reload-plugins в Claude Code (рестарт не нужен).

Channel-режим

Channels (research preview Claude Code v2.1.80+) — двусторонний bridge: входящие Telegram-сообщения сами появляются в активной Claude-сессии как XML-теги, Claude отвечает обратно через send_message.

Что под капотом

• В .mcp.json плагин выставляет CLAUDEGRAM_CHANNEL_MODE=1 → server/main.py объявляет experimental capabilities claude/channel и claude/channel/permission через кастомный stdio-runner (FastMCP сам не умеет — обходим через _mcp_server.create_initialization_options(experimental_capabilities=...)).

• server/channel.py подписывается на Telethon @client.on(events.NewMessage(incoming=True)).

• Каждое входящее от ID из allowlist (tg_allowed_sender_ids) пушится как raw JSONRPCNotification(method='notifications/claude/channel', ...) напрямую через write_stream stdio-сессии.

• Тег у Claude выглядит так:

  <channel source="claudegram"
           chat_id="-1001234567890"
           message_id="42"
           sender_id="111222333"
           user="Pete">
  привет, как дела?
  </channel>

• Skill tg-channel-incoming (auto-active) объясняет Claude'у, что делать с такими тегами + правила безопасности (никакого автоответа без подтверждения).

• Permission relay: ответные сообщения вида yes abcde / no abcde (5 строчных букв без l, regex case-insensitive) парсятся как verdict и шлются обратно как notifications/claude/channel/permission — Claude Code применяет автоматически.

Включение

Channel-режим opt-in через userConfig поле enable_channel_mode:

1. В /plugin интерфейсе или при первой установке выстави enable_channel_mode = "1".

2. Перезапусти Claude Code с обоими флагами:

   claude \
     --dangerously-load-development-channels plugin:claudegram@claudegram-local \
     --channels plugin:claudegram@claudegram-local

   В research preview кастомные плагины не входят в Anthropic allowlist (--dangerously-load-development-channels), а --channels явно регистрирует listener — оба флага нужны.

Если enable_channel_mode = "0" (default) — сервер работает только как tools-MCP, push'и не отсылаются, Telegram-rate-limit не тратится.

Удобно завести алиас в ~/.zshrc:

alias claude-tg='claude --dangerously-load-development-channels plugin:claudegram@claudegram-local --channels plugin:claudegram@claudegram-local'

Безопасность

Узнать свой sender_id для allowlist

После авторизации (claudegram-auth) — спроси у @userinfobot или вызови в активной Claude-сессии mcp__plugin_claudegram_claudegram__get_me.

Roadmap

• Outbound permission_request handler — Claude Code шлёт notifications/claude/channel/permission_request когда нужен approval; форвардить юзеру в Telegram. Сейчас inbound verdict работает, outbound forward — TODO (требует регистрации custom notification_handler в Server, не тривиально через FastMCP).

• send media (фото/документ/голосовое) — Telethon send_file уже умеет, обернуть в tool.

• pin / unpin / mute / archive / set_typing диалогов.

• Stories API (Telegram Stories через MTProto).

• Monitor на бэкап Saved Messages (monitors/monitors.json).

• Submit в Anthropic official marketplace — channel-плагины проходят security review, после чего работают без --dangerously-load-development-channels.

• Marketplace на GitHub + git-теги claudegram--v0.1.0 для version-constraints.