claudegram

<h1 align="center">Claudegram</h1> <p align="center"> <em>Личный Telegram-аккаунт как полноценный инструмент Claude Code — через MTProto, не Bot API.</em> </p> <p align="center"> <a href="https://github.com/sanjar-x/claudegram/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/sanjar-x/claudegram/actions/workflows/ci.yml/badge.svg"></a> <a href="https://github.com/sanjar-x/claudegram/actions/workflows/codeql.yml"><img alt="CodeQL" src="https://github.com/sanjar-x/claudegram/actions/workflows/codeql.yml/badge.svg"></a> <a href="https://github.com/sanjar-x/claudegram/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a> <a href="https://www.python.org/downloads/release/python-3140/"><img alt="Python 3.14+" src="https://img.shields.io/badge/python-3.14%2B-blue.svg"></a> <a href="https://github.com/astral-sh/ruff"><img alt="Code style: ruff" src="https://img.shields.io/badge/code%20style-ruff-261230.svg"></a> <a href="https://github.com/astral-sh/uv"><img alt="uv" src="https://img.shields.io/badge/managed%20by-uv-261230.svg"></a> <a href="https://modelcontextprotocol.io"><img alt="MCP" src="https://img.shields.io/badge/MCP-1.27%2B-8A2BE2.svg"></a> <a href="https://code.claude.com/docs/en/plugins-reference"><img alt="Claude Code Plugin" src="https://img.shields.io/badge/Claude%20Code-Plugin-D97757.svg"></a> </p> <p align="center"> <strong>120 MCP-tools</strong> · <strong>9 resources</strong> · <strong>6 templates</strong> · <strong>7 prompts</strong> · <strong>6 skills</strong> · <strong>4 уровня PreToolUse-гейтов</strong> </p>

---

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.

Возможности

| Слой | Что внутри | |-------------------|------------------------------------------------------------------------| | MCP-сервер | 118 типизированных tool'ов через FastMCP + Telethon, разбиты по 9 доменам с подпакетами в server/tools/ | | Production middleware | safe_tool decorator с graceful FloodWait/RPCError handling, latency logging, sensitive-sanitization | | Health probe | health_check + get_server_version для readiness/liveness | | Channel-режим | Push входящих Telegram-сообщений в активную сессию Claude как <channel source="claudegram"> теги + permission relay (yes/no <id>) | | Skills | 6 skill'ов: tg-digest, tg-search, tg-history, tg-send, tg-reply + фоновые telegram-workflow и tg-channel-incoming | | Hooks | SessionStart — авто-проверка авторизации; PreToolUse — гейт перед delete revoke=true (с jq/python3 fallback) | | bin/ | claudegram-auth — попадает в PATH Bash tool Claude Code (не в shell хоста); снаружи — uv run claudegram-auth | | userConfig | Креденшелы + sender-allowlist запрашиваются GUI-промптом плагина, сенситивные в системном keychain | | Persistent data | *.session живёт в ${CLAUDE_PLUGIN_DATA} — не теряется при апдейте плагина | | Marketplace | .claude-plugin/marketplace.json — каталог из одного плагина для /plugin install |

Структура

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 чатам.
• `/claudeg