Telegram-MCP

Автономный микросервис для стандартизации работы с Telegram Bot API через MCP (Model Context Protocol).

Централизует отправку сообщений, медиа, управление командами, приём вебхуков, prediction markets, календарь, Simple Icons (3300+ SVG), web-ui (Telegram Mini App) и предоставляет 128 MCP-инструментов для интеграции с LLM (Claude, ChatGPT и др.).

Полная поддержка Bot API 9.4 — стилизованные кнопки, аудио профиля, фото профиля бота, предложенные посты, form-топики, черновики, подарки, истории и многое другое.

✨ Возможности

📨 Сообщения

Отправка, редактирование, удаление с аудит-трейлом
HTML/MarkdownV2 форматирование
Reply-to-message, message threading (топики)
Pin/Unpin сообщений с тихим закреплением
Forward/Copy сообщений между чатами
Live сообщения (автоудаление через 30с)

🖼️ Медиа

Фото: URL, file_id, multipart upload
Видео: URL, file_id с preview
Документы: любые файлы с caption
Анимация/GIF: send_animation
Аудио: с метаданными (performer, title, duration)
Голосовые сообщения: voice messages
Стикеры: отправка по file_id
Медиа-группы (альбомы): 2-10 фото/видео одним сообщением

🎯 CommandHandler pattern (SDK)

Декоратор @api.command() для регистрации обработчиков
Guard-фильтры: chat_id, user_id для ограничения доступа
Long polling с автоматической обработкой обновлений
Парсинг аргументов команд
Синхронизация с Telegram (setMyCommands)

📊 Форматирование и шаблоны

Прогресс-бары: 6 стилей (classic, blocks, circles, squares, dots, minimal)
Emoji-градации: health (💚→💛→🧡→❤️→💔), status, priority, connection
Hardware state blocks: CPU, RAM, GPU, Disk, Network
Jinja2 шаблоны: хранение в БД, рендеринг на сервере
Auto-pin для прогресс-баров: автоматическое закрепление долгих процессов

👥 Chat Management

Ban/Unban: блокировка участников с опциями revoke_messages, until_date
Restrict: ограничение прав (can_send_messages, can_send_media, etc.)
Promote: повышение до админа с настройкой прав
Информация о чатах и участниках

🔔 Updates & Webhooks

Long polling: getUpdates с offset tracking
Webhooks: приём и хранение обновлений
Chat Actions: typing индикаторы (typing, upload_photo, record_video, etc.)
История обновлений с фильтрацией

🎨 Дополнительно

Опросы: создание polls и quiz с правильными ответами
Реакции: setMessageReaction (👍/🔥/❤️ и др.)
Callback queries: обработка inline-кнопок
Reply markup: inline/reply клавиатуры с расширенными кнопками
Rate limiting: token-bucket по chat_id
Retry: автоматический retry при 429/5xx
Python SDK: готовый клиент для интеграции
MCP: 128 инструментов для LLM

🚀 Bot API 9.1–9.4 (полная поддержка)

Bot API 9.4:

Стилизованные кнопки: button_style (primary, danger, success) + icon_custom_emoji_id для inline-кнопок
Аудио профиля: getUserProfileAudios — получение аудио профиля пользователя
Фото профиля бота: setMyProfilePhoto / removeMyProfilePhoto с InputProfilePhoto
Star-подписки: editUserStarSubscription — управление подписками пользователей

Bot API 9.3:

Черновики (sendMessageDraft): отправка черновиков в бизнес-чаты
Подарки: подарки премиум-подписок за звёзды, просмотр подарков пользователя/чата
Истории: репост историй между каналами, отправка/редактирование/удаление историй
Форум-топики в личных чатах: createForumTopic, editForumTopic, closeForumTopic и др.

Bot API 9.2:

Предложенные посты: approveSuggestedPost / declineSuggestedPost для бизнес-каналов
direct_messages_topic_id: маршрутизация сообщений в топики через Direct Messages
suggested_post_parameters: параметры для предложенных постов во всех send-методах

Bot API 9.1:

Чек-листы: интерактивные списки задач с галочками (до 30 элементов)
Звёзды: проверка баланса звёзд бота (getMyStarBalance)
Расширенные опросы: до 12 вариантов ответа

🎯 Prediction Markets (Polymarket-style)

Предсказания Stars с мультипликатором (непопулярный вариант = больший выигрыш)
Создание событий: фиксированная дата или автоматическое разрешение через LLM
Два режима: обезличенные (по умолчанию) или публичные (с именами)
LLM для принятия решений: интеграция с llm-mcp, Ollama, OpenRouter
Stars Payments: полная поддержка invoice, refund, transactions
Web-UI: интерфейс предсказаний в Telegram Mini App (при WEBUI_ENABLED=true)
MCP tools: 7 инструментов для автоматизации через LLM

📅 Календарь (Calendar v3 — Triggers & Actions)

Типы записей: событие, задача, триггер, монитор, голосование, рутина
Триггеры: одноразовые действия по расписанию (trigger_at → fire → result)
Мониторы: периодические проверки с тик-интервалами (5m, 10m, 1h, 6h, 1d)
Бюджет: оценка стоимости (cost_estimate) с сводкой за день/неделю/месяц
Действия (action JSONB): mcp_call, webhook, notify, create_entry, vote, noop
Результаты (result JSONB): статус, длительность, фактическая стоимость, цепочки
Источники: planner, arena, channel, bcs, trade, user, video, metrics
Месячная сетка с цветными точками событий + переключение на список
Поиск и фильтры: текст, статус, приоритет, теги, создатель, тип записи
Полноэкранная детализация: тип, триггер, действие, результат, стоимость, источник
MCP tools: 20 инструментов для управления через LLM

🌐 Web-UI (Telegram Mini App)

Страницы: создание HTML-страниц, открываемых как Mini App в Telegram
Опросники: динамические формы с конфигурируемыми полями
Prediction Markets: Polymarket-style интерфейс с коэффициентами и суммой
Owner-only дашборды: LLM, Metrics, Arena, Planner, Infra, BCS, Channel, K8s
Bee Design System: UI toolkit (BeeKit) + визуальные эффекты (BeeFX) + skeleton loading
Apache ECharts 6.0: графики для дашбордов (SVG renderer, lazy-load)
Индивидуальные ссылки: уникальные токены для персонализации
Telegram initData: автоматическая авторизация через HMAC-SHA256
TON Connect: подключение кошелька для TON-платежей
Stars Payments: оплата через Telegram.WebApp.openInvoice()
MCP tools: 6 инструментов для управления через LLM

Архитектура

┌─────────────────┐     ┌──────────────────┐     ┌──────────────┐
│   Потребители    │────▶│  tgapi            │────▶│ Telegram Bot  │
│  (SDK / curl)   │     │  (FastAPI :8081)  │     │     API       │
└─────────────────┘     └──────┬───────────┘     └──────────────┘
                               │
┌─────────────────┐     ┌──────▼───────────┐
│   LLM / Claude  │────▶│  tgmcp            │
│                 │     │  (Node.js :3335)  │
└─────────────────┘     └──────────────────┘
                               │
┌─────────────────┐     ┌──────▼───────────┐
│  Telegram TWA   │────▶│  tgweb            │
│  (Mini App)     │     │  (FastAPI :8443)  │
└─────────────────┘     └──────────────────┘
                               │
                        ┌──────▼───────────┐
                        │   PostgreSQL      │
                        │   (:5436)         │
                        └──────────────────┘

Компонент	Технология	Порт	Назначение
tgapi	Python / FastAPI	8081	HTTP API, вебхуки, шаблоны
tgmcp	Node.js / TypeScript	3335	MCP-тулзы + HTTP-мост
tgweb	Python / FastAPI	8443	Web-UI (Telegram Mini App) + Календарь
tgdb	PostgreSQL 16	5436	Сообщения, шаблоны, обновления, команды

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

# 1. Создать .env с токеном бота
cp .env.example .env
# Установить TELEGRAM_BOT_TOKEN в .env

# 2. Запустить
docker compose -f compose.yml up -d

# 3. Проверить
curl http://127.0.0.1:8081/health
curl http://127.0.0.1:3335/health
curl -sk https://127.0.0.1:8443/health

Примеры использования

curl

# Отправка сообщения
curl -X POST http://127.0.0.1:8081/v1/messages/send \
  -H 'content-type: application/json' \
  -d '{"chat_id": -100123456, "text": "<b>Привет!</b>", "parse_mode": "HTML"}'

# Отправка фото по URL
curl -X POST http://127.0.0.1:8081/v1/media/send-photo \
  -H 'content-type: application/json' \
  -d '{"chat_id": -100123456, "photo": "https://example.com/img.jpg", "caption": "Описание"}'

# Загрузка фото файлом
curl -X POST http://127.0.0.1:8081/v1/media/upload-photo \
  -F "chat_id=-100123456" \
  -F "caption=Загруженное фото" \
  -F "file=@/path/to/photo.jpg"

# Сообщение с inline-кнопками
curl -X POST http://127.0.0.1:8081/v1/messages/send \
  -H 'content-type: application/json' \
  -d '{
    "chat_id": -100123456,
    "text": "Выберите действие:",
    "reply_markup": {
      "inline_keyboard": [[
        {"text": "Да", "callback_data": "yes"},
        {"text": "Нет", "callback_data": "no"}
      ]]
    }
  }'

Python SDK

from telegram_api_client import TelegramAPI

async with TelegramAPI("http://localhost:8081") as api:
    # Отправка сообщения
    msg = await api.send_message(
        chat_id=-100123456,
        text="<b>Привет!</b>",
        parse_mode="HTML",
    )

    # Редактирование
    await api.edit_message(msg["id"], text="Обновлённый текст")

    # Отправка фото (файл)
    with open("chart.png", "rb") as f:
        await api.send_photo(chat_id=-100123456, photo=f, caption="График")

    # Прогресс-сообщение (send → edit → delete)
    async with api.progress(chat_id=-100123456) as p:
        await p.update(1, 3, "Загрузка данных...")
        await p.update(2, 3, "Обработка...")
        await p.update(3, 3, "Сохранение...")
    # Сообщение автоматически удаляется

MCP (для LLM)

# Список инструментов
curl http://127.0.0.1:3335/tools

# Вызов инструмента
curl -X POST http://127.0.0.1:3335/tools/messages.send \
  -H 'content-type: application/json' \
  -d '{"chat_id": -100123456, "text": "Привет от LLM"}'

Структура проекта

Telegram-MCP/
├── api/                    # FastAPI-сервис
│   ├── app/
│   │   ├── main.py         # Точка входа, lifespan, роутеры
│   │   ├── config.py       # Настройки (pydantic-settings)
│   │   ├── db.py           # PostgreSQL connection pool
│   │   ├── utils.py        # Общие хелперы (escape_html, resolve_bot_context)
│   │   ├── telegram_client.py  # httpx-клиент к Telegram Bot API
│   │   ├── rate_limiter.py     # Token-bucket rate limiter
│   │   ├── templates.py    # Jinja2-рендеринг
│   │   ├── models.py       # Pydantic-модели
│   │   ├── routers/        # Эндпоинты (20 роутеров)
│   │   │   ├── messages.py     # Сообщения, черновики, forward/copy
│   │   │   ├── media.py        # Фото, документы, видео, аудио, стикеры
│   │   │   ├── polls.py        # Опросы и викторины
│   │   │   ├── reactions.py    # Реакции
│   │   │   ├── predictions.py  # Рынки предсказаний
│   │   │   ├── templates.py    # Шаблоны
│   │   │   ├── commands.py     # Команды бота
│   │   │   ├── callbacks.py    # Callback queries
│   │   │   ├── chats.py        # Чаты и участники
│   │   │   ├── webhook.py      # Вебхуки
│   │   │   ├── bots.py         # Мультибот, профиль бота
│   │   │   ├── forums.py       # Форум-топики
│   │   │   ├── stories.py      # Истории каналов
│   │   │   ├── suggested_posts.py # Предложенные посты (9.2)
│   │   │   ├── checklists.py   # Чек-листы, звёзды, подарки
│   │   │   ├── calendar.py     # Календарь: CRUD, bulk, history
│   │   │   ├── webui.py        # Proxy → tgweb
│   │   │   └── health.py       # Healthcheck, метрики
│   │   └── services/       # Бизнес-логика
│   │       ├── predictions.py  # Сервис предсказаний
│   │       ├── calendar.py     # Сервис календаря
│   │       ├── keyboards.py    # Билдеры inline-клавиатур
│   │       └── ...
│   └── Dockerfile
├── mcp/                    # MCP-сервер (Node.js)
│   ├── src/
│   │   ├── index.ts        # Регистрация модулей
│   │   ├── types.ts        # Общие типы (ToolDef, ApiRequestFn)
│   │   └── tools/          # Модули по доменам (128 инструментов)
│   │       ├── messages.ts, media.ts, chats.ts, ...
│   │       ├── predictions.ts, balance.ts, stars.ts
│   │       ├── bots.ts     # Мультибот + профиль
│   │       ├── forums.ts   # Форум-топики
│   │       ├── stories.ts  # Истории
│   │       ├── suggested_posts.ts # Предложенные посты
│   │       ├── calendar.ts # Календарь (20 инструментов)
│   │       ├── icons.ts    # Simple Icons (icons.resolve)
│   │       └── webui.ts    # Web-UI инструменты
│   └── Dockerfile
├── web-ui/                 # Web-UI (Telegram Mini App)
│   ├── app/
│   │   ├── main.py         # FastAPI + Jinja2 + static
│   │   ├── config.py       # Settings
│   │   ├── db.py           # PostgreSQL pool
│   │   ├── auth.py         # Telegram initData HMAC-SHA256
│   │   ├── routers/        # health, pages, render, module_proxy
│   │   ├── services/       # pages, links, access, roles
│   │   ├── templates/      # base, hub, llm, metrics, arena, planner, infra, ...
│   │   └── static/         # style.css, bee-kit.js, bee-fx.js, echarts, twa.js
│   ├── docs/               # UI-GUIDE.md, CHANGELOG.md
│   └── Dockerfile
├── sdk/                    # Python SDK
│   └── telegram_api_client/
│       ├── client.py       # TelegramAPI + ProgressContext
│       └── exceptions.py   # TelegramAPIError
├── db/init/                # SQL-миграции
│   ├── 01_schema.sql       # Основная схема
│   ├── 02_extensions.sql   # Медиа, callbacks, webhook config
│   ├── 10_web_ui.sql       # Web-UI таблицы
│   └── 11_calendar.sql     # Календарь
├── templates/              # Jinja2-шаблоны (auto-seed)
├── scripts/                # Тестовые скрипты
├── docs/                   # Документация
└── compose.yml             # Docker Compose (tgdb, tgapi, tgmcp, tgweb)

Документация

docs/api.md — справочник HTTP API
docs/sdk.md — Python SDK
docs/commands.md — управление командами бота
docs/webhooks.md — вебхуки и обновления
docs/mcp.md — MCP-инструменты
docs/web-ui.md — Web-UI (Telegram Mini App)
web-ui/docs/UI-GUIDE.md — Bee Design System (разработчикам)
docs/formatting.md — форматирование сообщений Telegram
docs/schema.md — схема базы данных

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

Переменная	Описание	По умолчанию
`TELEGRAM_BOT_TOKEN`	Токен бота из @BotFather	— (обязательно)
`DB_USER`	Пользователь БД	`telegram`
`DB_PASSWORD`	Пароль БД	`telegram`
`DB_NAME`	Имя БД	`telegram`
`PORT_DB_TG`	Внешний порт PostgreSQL	`5436`
`PORT_HTTP_TGAPI`	Внешний порт API	`8081`
`PORT_MCP_TG`	Внешний порт MCP	`3335`
`TELEGRAM_API_URL`	Явный URL API для MCP bridge	`http://tgapi:8000`
`TELEGRAM_API_BASE`	Legacy alias для URL API	`http://tgapi:8000`
`API_PORT`	Legacy fallback для порта API	`8081`
`MCP_HTTP_PORT`	Legacy fallback для порта MCP	`3335`
`MCP_HTTP_TOKEN`	Bearer-токен для MCP HTTP	— (опционально)
`TEMPLATE_AUTOSEED`	Автозагрузка шаблонов из `templates/`	`true`
`WEBUI_ENABLED`	Включить web-ui (web_app кнопки)	`false`
`WEBUI_PUBLIC_URL`	Публичный URL для Mini App	—
`PORT_WEBUI`	Внешний порт web-ui	`8443`

Если TELEGRAM_API_URL/TELEGRAM_API_BASE не заданы, MCP сначала использует http://tgapi:8000. Для обратной совместимости на 1 релиз при ошибке сети выполняется retry на legacy http://telegram-api:8000.

Лицензия

MIT

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Telegram-MCP

✨ Возможности

📨 Сообщения

🖼️ Медиа

🎯 CommandHandler pattern (SDK)

📊 Форматирование и шаблоны

👥 Chat Management

🔔 Updates & Webhooks

🎨 Дополнительно

🚀 Bot API 9.1–9.4 (полная поддержка)

🎯 Prediction Markets (Polymarket-style)

📅 Календарь (Calendar v3 — Triggers & Actions)

🌐 Web-UI (Telegram Mini App)

Архитектура

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

Примеры использования

curl

Python SDK

MCP (для LLM)

Структура проекта

Документация

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

Лицензия

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Telegram-MCP

✨ Возможности

📨 Сообщения

🖼️ Медиа

🎯 CommandHandler pattern (SDK)

📊 Форматирование и шаблоны

👥 Chat Management

🔔 Updates & Webhooks

🎨 Дополнительно

🚀 Bot API 9.1–9.4 (полная поддержка)

🎯 Prediction Markets (Polymarket-style)

📅 Календарь (Calendar v3 — Triggers & Actions)

🌐 Web-UI (Telegram Mini App)

Архитектура

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

Примеры использования

curl

Python SDK

MCP (для LLM)

Структура проекта

Документация

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

Лицензия