telegram-mcp
MCP-сервер на Go для работы с Telegram через один или несколько пользовательских аккаунтов (MTProto,
gotd/td). Сервер отдаёт MCP-клиенту чаты, сообщения,
медиа и локальную аналитику, а при явном включении write-режима умеет публиковать
и редактировать посты.
Суммаризацию выполняет MCP-клиент: telegram-mcp отвечает только за получение и
изменение данных Telegram.
Изначальная версия проекта создана @linemk. Инструменты
send_message, watchlist и готовый скрипт ежедневного дайджеста (scripts/) добавлены
им же в рамках совместной разработки.
[!WARNING] Авторизация пользовательским аккаунтом через сторонний MTProto-клиент может противоречить правилам Telegram. Используйте отдельный аккаунт и собственные
api_id/api_hash. Риск блокировки нельзя исключить.
Возможности
Чтение и локальная аналитика
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 и выполняют реальные действия от имени авторизованного
аккаунта.
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.

Требования
- macOS или Linux;
- Go 1.25+;
- Telegram
api_idиapi_hashиз my.telegram.org; - MCP-клиент: Codex, Claude Desktop или другой клиент с поддержкой stdio MCP.
Быстрая установка
Впервые ставите и нужен разбор по шагам (получение
api_id/api_hashс типовыми ошибками, логин, подключение клиента, раздача сборок) — см. SETUP.md.
git clone https://github.com/20grizz03/telegram-mcp.git
cd telegram-mcp
chmod +x install.sh
./install.sh
Установщик:
- запросит ваши Telegram credentials;
- соберёт бинарник локально;
- проведёт одноразовый Telegram login;
- создаст защищённые
mcp.envиrun-server.shвTGMCP_HOME; - предложит подключить сервер к Codex и/или Claude Desktop.
По умолчанию данные хранятся в ~/.config/tg-mcp. Полностью перезапустите
MCP-клиент после установки.
Ручная установка
1. Сборка
go build -o bin/tgmcp ./cmd/tgmcp
2. Одноразовый login
export TG_APP_ID=123456
export TG_APP_HASH=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Необязательно: export TG_PHONE=+1234567890
./bin/tgmcp login
Код подтверждения придёт в 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.
3. Запуск MCP-сервера
export TG_APP_ID=123456
export TG_APP_HASH=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
./bin/tgmcp serve
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:
{
"mcpServers": {
"telegram": {
"command": "/absolute/path/to/.config/tg-mcp/run-server.sh"
}
}
}
Конфигурация
Диапазоны времени в 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-агент