mcp-telegram

MCP-сервер, который подключает ИИ-ассистентов, таких как Claude, к вашему реальному аккаунту Telegram через User API (MTProto). Это не бот — Claude читает и отправляет сообщения от вашего имени.

Создан с использованием gotd/td и официального MCP Go SDK.

Условия использования Telegram API: Этот проект использует Telegram User API. Вы должны получить собственные api_id и api_hash на сайте my.telegram.org и соблюдать Условия использования Telegram API. Неправомерное использование User API (спам, массовая рассылка, парсинг) может привести к блокировке вашего аккаунта. Вы несете единоличную ответственность за то, как используете этот инструмент.

Содержание

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

• Что можно делать с помощью этого инструмента

• Сравнение с chaindead/telegram-mcp

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

• Настройка клиента

• Справочник конфигурации

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

Возможности

Дополнительные возможности:

• Отправка файлов и фотографий

• Пересылка сообщений между чатами

• Ответы на конкретные сообщения

• Загрузка фотографий и документов из истории сообщений

• Фильтрация истории по диапазону дат (since / until)

• Типизированные ссылки на объекты (user:ID, chat:ID, channel:ID) для предотвращения конфликтов ID

• «Ленивое» разрешение объектов — позволяет избежать ошибок FLOOD_WAIT при запуске

• Глобальное ограничение частоты запросов на уровне RPC

Что можно делать с помощью этого инструмента

После подключения вы можете просить своего ИИ-ассистента о следующем:

Просмотр сообщений

• «Проверь мои непрочитанные сообщения в Telegram и сделай краткую сводку»

• «Что написала @alice за последние 24 часа?»

• «Покажи мне сообщения из чата Dev Team с понедельника»

Ответы и общение

• «Подготовь черновик ответа на последнее сообщение от @bob — пока не отправляй»

• «Отправь 'звучит неплохо, давай встретимся в 3 часа дня' пользователю @alice»

• «Ответь на сообщение 1234 в чате проекта с моим отзывом»

Управление входящими

• «Пометь все сообщения в новостном канале как прочитанные»

• «В каких из моих разрешенных чатов есть непрочитанные сообщения?»

• «Загрузи фотографии из сегодняшних сообщений в чате дизайна»

Исследования и анализ

• «Найди все сообщения с упоминанием развертывания (deployment) за последнюю неделю»

• «Обобщи обсуждение в командном чате за вчерашний день»

• «Какие файлы были отправлены в канал проекта в этом месяце?»

Сравнение с chaindead/telegram-mcp

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

Предварительные требования

• Go 1.26+

• Аккаунт Telegram

• API-учетные данные с my.telegram.org (api_id и api_hash)

Установка

Homebrew (macOS / Linux):

brew install Prgebish/tap/mcp-telegram

Готовые бинарные файлы (macOS / Linux / Windows):

Скачайте с GitHub Releases.

Go install:

go install github.com/Prgebish/mcp-telegram/cmd/mcp-telegram@latest

Из исходного кода:

git clone https://github.com/Prgebish/mcp-telegram.git
cd mcp-telegram
go build ./cmd/mcp-telegram

Это создаст файл mcp-telegram (или mcp-telegram.exe в Windows) в текущей директории.

Аутентификация

Запустите команду аутентификации один раз, чтобы создать файл сессии. Вас попросят ввести номер телефона, код подтверждения и (если включено) пароль двухфакторной аутентификации.

macOS / Linux:

export TG_APP_ID=12345
export TG_API_HASH="your_api_hash"

mcp-telegram auth --config config.yaml

Windows (PowerShell):

$env:TG_APP_ID = "12345"
$env:TG_API_HASH = "your_api_hash"

mcp-telegram.exe auth --config config.yaml

Windows (cmd):

set TG_APP_ID=12345
set TG_API_HASH=your_api_hash

mcp-telegram.exe auth --config config.yaml

Конфигурация

Создайте файл config.yaml:

telegram:
  app_id: ${TG_APP_ID}
  api_hash: ${TG_API_HASH}
  session_path: ~/.config/mcp-telegram/session.json

acl:
  chats:
    - match: "@username"
      permissions: [read, draft, mark_read]
    - match: "user:123456789"
      permissions: [read, send]
    - match: "channel:2225853048"
      permissions: [read, mark_read]

limits:
  max_messages_per_request: 50
  max_dialogs_per_request: 100
  rate:
    requests_per_second: 2.0
    burst: 3

logging:
  level: info

Переменные окружения в синтаксисе ${...} раскрываются при загрузке.

Настройка клиента

Сервер общается через stdio — ваш MCP-клиент запускает и управляет процессом.

Claude Code (CLI — добавьте через команду):

claude mcp add telegram -- /path/to/mcp-telegram serve --config /path/to/config.yaml

Claude Desktop / Claude Code (~/.claude.json или claude_desktop_config.json):

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/mcp-telegram",
      "args": ["serve", "--config", "/path/to/config.yaml"],
      "env": {
        "TG_APP_ID": "12345",
        "TG_API_HASH": "your_api_hash"
      }
    }
  }
}

Cursor (Настройки > MCP Servers > Добавить):

{
  "telegram": {
    "command": "/path/to/mcp-telegram",
    "args": ["serve", "--config", "/path/to/config.yaml"],
    "env": {
      "TG_APP_ID": "12345",
      "TG_API_HASH": "your_api_hash"
    }
  }
}

Конфигурация

ACL

ACL работает по принципу «запрещено по умолчанию». Доступны только те чаты, которые явно указаны в acl.chats, и только с теми правами, которые вы укажете.

Поддерживаемые шаблоны сопоставления:

Типы разрешений: read, send, draft, mark_read.

Если один и тот же объект соответствует нескольким правилам (например, через @username и user:ID), права объединяются — они никогда не перекрывают друг друга.

Ограничение частоты запросов

Секция limits.rate настраивает глобальный «token bucket», который оборачивает все RPC-вызовы Telegram:

• requests_per_second — устойчивая скорость (по умолчанию: 2.0)

• burst — максимальный размер всплеска (по умолчанию: 3)

Загрузка медиа

media:
  download: [photo, document, video, voice, audio]
  directory: ~/telegram-media
  allowed_upload_dirs:
    - ~/Documents
    - ~/Downloads

При настройке tg_history будет автоматически загружать медиафайлы в указанную директорию. Параметр download_to может переопределить путь, но только в пределах media.directory или её поддиректорий.

allowed_upload_dirs ограничивает директории, из которых tg_send может читать файлы. Отправка файлов отключена, если это не настроено.

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

• ACL «запрещено по умолчанию» — никакой чат не доступен, если он явно не добавлен в белый список

• Границы файловой системы — tg_send может читать файлы только из allowed_upload_dirs; download_to ограничен поддиректориями media.directory

• Права доступа к файлу сессии — принудительно устанавливаются в 0600 (чтение/запись только владельцем)

• Отсутствие логирования секретов — API-хэши, токены сессий и ключи авторизации никогда не записываются в логи

• Отсутствие доступа к хэшам доступа — внутренние хэши доступа Telegram удаляются из всех выходных данных инструментов

• Ограничение частоты запросов — предотвращает случайное злоупотребление API

• Локальный часовой пояс — фильтры дат используют часовой пояс вашей системы, а не UTC

Лицензия

MIT

Если вы находите этот проект полезным, пожалуйста, поставьте звезду — это помогает другим узнать о нем.