MCP-сервер на Go для работы с Telegram через один или несколько пользовательских аккаунтов (MTProto,
gotd/td). Сервер отдаёт MCP-клиенту чаты, сообщения,
медиа и локальную аналитику, а при явном включении write-режима умеет публиковать
и редактировать посты.
Суммаризацию выполняет MCP-клиент: telegram-mcp отвечает только за получение и
изменение данных Telegram.
MCP server for Telegram: chat history, local analytics, media, and opt-in channel publishing.
Изначальная версия проекта создана @linemk. Инструменты
send_message, watchlist и готовый скрипт ежедневного дайджеста (scripts/) добавлены
им же в рамках совместной разработки.
[!WARNING]
Авторизация пользовательским аккаунтом через сторонний MTProto-клиент может
противоречить правилам Telegram. Используйте отдельный аккаунт и собственные
api_id/api_hash. Риск блокировки нельзя исключить.
Возможности
Чтение и локальная аналитика
Tool
Назначение
list_accounts
Доступные аккаунты и аккаунт по умолчанию
list_chats
Список диалогов с типом, username и числом непрочитанных сообщений
list_topics
Топики форум-супергруппы
read_chat
История за период с авторами, метриками и ссылками на сообщения
get_channel_profile
Описание, число подписчиков и связанный чат обсуждения
list_pinned_messages
Закреплённые сообщения
list_scheduled_posts
Очередь отложенных постов
list_invite_links
Invite links и их статистика
list_channel_folders
Пользовательские папки Telegram
sync_chat
Инкрементальная синхронизация в локальный SQLite
search_chat
Полнотекстовый поиск по локальному кэшу
search_channels
Глобальный поиск публичных Telegram-каналов, включая каналы без подписки
search_public_posts
Глобальный поиск публикаций в публичных каналах с проверкой бесплатной квоты и запретом списания Stars
download_media
Скачивание вложения конкретного сообщения
capture_growth_snapshot
Локальный снимок аудитории и медианных метрик постов
Локальный watchlist чатов/топиков для ежедневного дайджеста, с per-chat focus (что извлекать/пропускать)
CRM, preferences, snapshots, watchlist и outreach drafts хранятся только в
отдельном SQLite выбранного аккаунта. Эти инструменты не отправляют сообщения в
Telegram. Каждый MCP-tool, кроме list_accounts, принимает необязательное поле
account; без него используется аккаунт по умолчанию.
search_public_posts может использовать один из бесплатных дневных запросов,
выдаваемых Telegram. Перед поиском сервер проверяет квоту и не выполняет запрос,
если он требует оплаты. Поле allow_paid_stars не передаётся ни при каких
условиях, поэтому инструмент не может списать Stars.
Запись
Write-инструменты выключены по умолчанию. Они появляются только при
TGMCP_ENABLE_WRITE=1 и выполняют реальные действия от имени авторизованного
аккаунта.
Tool
Назначение
publish_post
Публикация текста или фото, сразу или по расписанию
Изменение текста или подписи ожидающего отложенного поста
delete_scheduled_post
Удаление ожидающего поста из очереди публикаций
pin_post
Закрепление или открепление поста
forward_post
Нативная пересылка сообщения в другой чат
create_invite_link
Создание маркированной администраторской ссылки
create_shared_folder
Создание и экспорт папки с каналами/группами
update_chat_description
Изменение или очистка описания группы, супергруппы или канала
update_profile_bio
Изменение или очистка bio текущего Telegram-профиля
send_message
Отправка текстового или Telegram-HTML сообщения в чат/канал (напр. доставка дайджеста); topic_id для форум-топика, html для <b>/<i>/<a>
publish_rich_post и edit_rich_post используют нативный Rich Text Telegram
(MTProto layer 227) и требуют Premium у авторизованного аккаунта. Передайте
ровно одно поле: markdown или html. Поддерживаются заголовки, таблицы,
списки, цитаты, блоки кода, формулы, details и медиа между абзацами. Внешнее
медиа можно вставлять обычным HTTP(S)-URL. Локальное фото передаётся в photos
с коротким id, а в тексте размещается как .
Пример Rich Markdown:
# Короткий разбор релиза
| Что изменилось | Практический эффект |
| --- | --- |
| Новый API | Меньше ручного кода |
> Ограничение: функция пока доступна только Premium.

Код подтверждения придёт в Telegram. Если включена 2FA, сервер также запросит
пароль. Сессия будет сохранена в ~/.config/tg-mcp/session.json.
Чтобы добавить второй аккаунт, задайте ему короткое локальное имя:
./bin/tgmcp login --account work
./bin/tgmcp login --account family
./bin/tgmcp accounts
./bin/tgmcp check --account work
Текущий однопользовательский session.json остаётся аккаунтом default и никуда
не переносится. Именованные аккаунты изолированы в
~/.config/tg-mcp/accounts/<name>/ — у каждого свои session.json и cache.db.
serve автоматически находит default и все именованные сессии, одновременно
подключает их и добавляет поле account во все инструменты. Можно ограничить
набор через TGMCP_ACCOUNTS=default,work, а аккаунт по умолчанию выбрать через
TGMCP_DEFAULT_ACCOUNT=work.
Для безопасного постоянного подключения рекомендуется использовать
run-server.sh, который создаёт install.sh, а не хранить credentials прямо в
конфигурации MCP-клиента.
Codex
codex mcp add telegram -- "$HOME/.config/tg-mcp/run-server.sh"
codex mcp list
Claude Desktop
Добавьте runner в mcpServers файла claude_desktop_config.json:
Каталог с session и SQLite; по умолчанию ~/.config/tg-mcp
TG_PHONE
нет
Номер телефона для login
TG_PASSWORD
нет
2FA-пароль для login
TGMCP_ENABLE_WRITE
нет
1, true или yes включает реальные write-tools
TGMCP_ACCOUNT
нет
Аккаунт для CLI-команды и digest-скрипта
TGMCP_ACCOUNTS
нет
Список аккаунтов для serve через запятую; без него сессии находятся автоматически
TGMCP_DEFAULT_ACCOUNT
нет
Аккаунт MCP по умолчанию, когда tool-вызов не передал account
Диапазоны времени в read_chat: today, yesterday, 7d, 24h, 30m, дата
2026-06-15 или RFC3339. Для будущих scheduled_at и expires_at доступны
7d, 24h, 30m, дата или RFC3339.
Примеры запросов
«Покажи список моих чатов»
«Покажи аккаунты и чаты аккаунта work»
«Найди публичные Telegram-каналы про AI art»
«Найди публикации про генерацию коротких видео в публичных каналах»
«Саммаризируй чат 1234567890 за последние 7 дней»
«Скачай фото из сообщения 50000 в чате 1234567890»
«Добавь Example Channel в кандидаты на взаимный репост»
«Опубликуй этот текст завтра в 10:00 без уведомления» — только в write-режиме
Ежедневный дайджест
scripts/daily-digest.sh собирает один дайджест в день из watchlist чатов и
доставляет его в выбранный Telegram-чат. Весь Telegram-I/O идёт через
детерминированный CLI (sync/dump/send), а LLM используется только как
суммаризатор текста на stdin (без MCP), поэтому джоба не конфликтует с запущенным
tgmcp serve. Набор чатов задаётся через tgmcp watch add ..., поэтому добавление
чата не требует правок скрипта. Подробнее — в scripts/README.md.
Дополнительные CLI-команды помимо login/serve:
tgmcp accounts # список аккаунтов
tgmcp login --account work # добавить аккаунт
tgmcp --account work check # выбрать аккаунт
tgmcp send [--html] <chat_id> "<text>" [topic_id] # отправить сообщение
tgmcp dump <chat_id> [from] [topic_id] # полный текст окна (вход дайджеста)
tgmcp watch add <chat_id> [topics_csv] [--label ..] [--focus ..] | watch list [--plain] | watch rm <id>
Безопасность и приватность
Никогда не коммитьте api_hash, телефон, 2FA-пароль или Telegram session.
session.json, mcp.env, .env, SQLite-файлы, бинарники и каталоги данных
исключены через .gitignore.
Write-tools отключены по умолчанию и требуют явного TGMCP_ENABLE_WRITE=1.
Для read-only использования не добавляйте write-флаг в окружение сервера.
Перед публикацией форка или архива повторно проверьте его secret scanner'ом.
Разработка
go test ./...
go vet ./...
Структура проекта:
cmd/tgmcp/ CLI: login, serve, send, dump, watch и локальные команды
internal/accounts реестр аккаунтов и одновременный lifecycle Telegram-клиентов
internal/config env-конфигурация и пути данных
internal/tgclient MTProto-клиент и Telegram operations (вкл. send.go)
internal/store SQLite cache, preferences, CRM, snapshots и watchlist
internal/syncer синхронизация истории
internal/mcpserver MCP tools и handlers
scripts/ ежедневный дайджест (daily-digest.sh) и launchd-агент
T
Telegram
20grizz03·3 ดาว·
MCP server for Telegram: chat history, local analytics, media, and opt-in channel publishing.