Telegram MCP Server

📖 Документация · ☁️ Облачная версия — подключите Telegram к Claude.ai или ChatGPT за 30 секунд с помощью QR-кода, без API-ключей.

Telegram MCP Server — сервер Model Context Protocol, который подключает AI-ассистентов, таких как Claude и ChatGPT, к Telegram через протокол MTProto. В отличие от ботов, он работает как userbot — от имени вашей личной учётной записи Telegram и с использованием GramJS, поэтому получает полный доступ к вашим чатам, контактам и истории сообщений.

Возможности

Полный набор инструментов — один из наиболее функциональных серверов Telegram MCP
Протокол MTProto — прямой доступ к API Telegram, без ограничений Bot API
Userbot — работает от имени вашей личной учётной записи, а не как бот
Расширенные возможности — отправка сообщений, реакции, опросы, отложенные сообщения, стикеры, медиафайлы, контакты и многое другое
Темы форума — просмотр списка тем и сообщений в каждой из них, отправка сообщений в выбранные темы, получение числа непрочитанных сообщений по темам
Стикеры — поиск наборов стикеров, просмотр установленных и недавно использованных стикеров, отправка стикеров в любые чаты
Управление учётной записью и профилем — изменение профиля, установка эмодзи-статуса, даты рождения, личного канала и фотографии профиля, настройка параметров приватности, управление сессиями и таймерами автоматического удаления
Папки чатов — создание, изменение и удаление папок, изменение их порядка, включение и отключение тегов папок, просмотр предлагаемых папок (v1.33.0)
Общие настройки приватности — просмотр и настройка параметров приватности для всей учётной записи (v1.33.0)
Глобальный поиск — поиск сообщений сразу во всех чатах
Опрос обновлений в реальном времени — получение обновлений с помощью курсоров без сохранения состояния; агент самостоятельно хранит состояние {pts, qts, date}
Инлайн-боты и кнопки — отправка запросов инлайн-ботам, передача результатов и нажатие кнопок обратного вызова
Истории — просмотр историй контактов и статистики просмотров; публикация, изменение и удаление историй, отправка реакций, закрепление, скрытый режим, архивирование и отправка жалоб (v1.30.0)
Обсуждения — получение сведений о группе обсуждения для публикаций канала с комментариями, просмотр списка групп, в которых можно вести обсуждения (v1.30.0)
Отметки о прочтении — информация о том, кто прочитал сообщение в небольшой группе, и когда было прочитано ваше личное сообщение (v1.30.0)
Управление каналом — включение и отключение подписей к публикациям, защиты от спама, режима форума и доступа к истории сообщений; одобрение запросов на вступление
Статистика — аналитика каналов и супергрупп (GetBroadcastStats / GetMegagroupStats)
Бусты и бизнес-функции — статус бустов, список пользователей, отправивших буст, создание, изменение и удаление ссылок на чаты Telegram Business, настройка рабочего времени, местоположения, приветственных сообщений, сообщений об отсутствии и описаний
Подарки за Stars — просмотр доступных и сохранённых подарков, сохранение и конвертация подарков, управление балансом Stars и подписками (включается через MCP_TELEGRAM_ENABLE_STARS=1, v1.34.0)
Общий демон — один фоновый процесс обслуживает несколько клиентов MCP через одну сессию Telegram; см. руководство по общему демону (v1.38.0)
Вход по QR-коду — авторизация с помощью сканирования QR-кода в приложении Telegram
Сохранение сессии — войдите один раз и оставайтесь подключёнными после перезапусков
Понятный вывод — отображаются имена отправителей, а не только числовые идентификаторы
Совместимость с любыми клиентами MCP — Claude Code, Claude Desktop, ChatGPT, Cursor, VS Code, Mastra и другие

Требования

Node.js версии 18 или выше
Учётные данные Telegram API — API_ID и API_HASH с сайта my.telegram.org

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

1. Получите учётные данные Telegram API

Перейдите на my.telegram.org и войдите, указав номер телефона.
Откройте раздел API development tools.
Создайте новое приложение, указав любое имя и платформу.
Скопируйте значения App api_id и App api_hash.

2. Войдите в систему

TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH npx @overpod/mcp-telegram login

В терминале появится QR-код. Откройте Telegram на телефоне, перейдите в Настройки > Устройства > Подключить устройство, затем отсканируйте код. Сессия сохранится в ~/.mcp-telegram/session и будет использоваться автоматически.

Другой путь для сессии: задайте TELEGRAM_SESSION_PATH=/path/to/session, чтобы сохранять файл сессии в другом месте.

Двухэтапная проверка (2FA): если для вашей учётной записи включён облачный пароль, одного сканирования QR-кода недостаточно — Telegram также запросит пароль. Передайте его через TELEGRAM_2FA_PASSWORD, чтобы завершить вход:

TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH TELEGRAM_2FA_PASSWORD=YOUR_PASSWORD npx @overpod/mcp-telegram login

Пароль используется только локально для ответа на запрос SRP от Telegram и нигде не сохраняется.

3. Добавьте сервер в Claude

claude mcp add telegram -s user \
  -e TELEGRAM_API_ID=YOUR_ID \
  -e TELEGRAM_API_HASH=YOUR_HASH \
  -- npx @overpod/mcp-telegram

Готово! Попросите Claude выполнить telegram-status, чтобы проверить подключение.

Несколько учётных записей

Используйте TELEGRAM_SESSION_PATH, чтобы одновременно работать с несколькими учётными записями Telegram:

# Login each account with a unique session path
TELEGRAM_API_ID=ID1 TELEGRAM_API_HASH=HASH1 TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-work npx @overpod/mcp-telegram login
TELEGRAM_API_ID=ID2 TELEGRAM_API_HASH=HASH2 TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-personal npx @overpod/mcp-telegram login

Затем добавьте каждую учётную запись как отдельный сервер MCP:

claude mcp add telegram-work -s user \
  -e TELEGRAM_API_ID=ID1 \
  -e TELEGRAM_API_HASH=HASH1 \
  -e TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-work \
  -- npx @overpod/mcp-telegram

claude mcp add telegram-personal -s user \
  -e TELEGRAM_API_ID=ID2 \
  -e TELEGRAM_API_HASH=HASH2 \
  -e TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-personal \
  -- npx @overpod/mcp-telegram

Для каждой учётной записи создаётся отдельный файл сессии — конфликты исключены.

Несколько агентов или параллельных клиентов (общий демон)

В отличие от использования нескольких учётных записей, здесь одна учётная запись одновременно используется несколькими клиентами — например, несколькими окнами Claude Code, параллельными субагентами или разными IDE. Обычно каждый процесс открывает одну и ту же сессию, из-за чего процессы вытесняют друг друга с ошибкой AUTH_KEY_DUPLICATED. Режим serve решает эту проблему.

Запустите один постоянно работающий демон, который будет управлять единственным подключением к Telegram. Все остальные процессы автоматически обнаружат демон через блокировку PID и станут клиентами, перенаправляющими вызовы инструментов через локальный Unix-сокет:

# On the host, once: start the daemon (owns the connection, no stdio)
TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH mcp-telegram serve
# (or set MCP_TELEGRAM_DAEMON=1 instead of the `serve` argument)

Затем укажите для каждого клиента MCP одну и ту же установку и один и тот же TELEGRAM_SESSION_PATH — без аргумента serve. Клиенты подключатся к демону автоматически; закрытие любого клиента не разорвёт общее подключение. Учётные данные нужны только демону, который управляет подключением, поэтому в командах запуска клиентов можно не указывать TELEGRAM_API_ID и TELEGRAM_API_HASH, а хранить их в окружении, где запущен демон.

Инструкции по настройке systemd и использованию SSH см. в руководстве по общему демону.

Поддержка прокси

Если Telegram заблокирован или вы работаете в контейнерной среде (Docker, K3s), используйте SOCKS5 или MTProxy:

# SOCKS5 proxy
TELEGRAM_PROXY_IP=127.0.0.1 \
TELEGRAM_PROXY_PORT=10808 \
npx @overpod/mcp-telegram

# MTProxy
TELEGRAM_PROXY_IP=proxy.example.com \
TELEGRAM_PROXY_PORT=443 \
TELEGRAM_PROXY_SECRET=ee00000000000000000000000000000000 \
npx @overpod/mcp-telegram

Переменная	Описание
`TELEGRAM_PROXY_IP`	Адрес прокси-сервера
`TELEGRAM_PROXY_PORT`	Порт прокси-сервера
`TELEGRAM_PROXY_SOCKS_TYPE`	`4` или `5` (по умолчанию: `5`)
`TELEGRAM_PROXY_SECRET`	Секрет MTProxy (включает режим MTProxy)
`TELEGRAM_PROXY_USERNAME`	Имя пользователя для прокси, необязательно
`TELEGRAM_PROXY_PASSWORD`	Пароль для прокси, необязательно

Подключение через WSS (порт 443)

Если ваш VPS или хостинг доступен для исходящих подключений через порт 443, но не через стандартный порт MTProto 80 (некоторые облачные провайдеры блокируют порт 80 для диапазонов IP-адресов Telegram DC в рамках политики защиты от злоупотреблений), задайте:

TELEGRAM_USE_WSS=true npx @overpod/mcp-telegram

Переменная Описание

TELEGRAM_USE_WSS Если задано значение true, gramJS использует порт 443 вместо 80 для транспорта MTProto TCPFull. По умолчанию: false. Нельзя использовать одновременно с TELEGRAM_PROXY_* (ограничение gramJS): если заданы оба параметра, useWSS игнорируется, а прокси имеет приоритет; в журнал записывается предупреждение.

Варианты установки

npx (рекомендуется, установка не требуется)

Клонировать репозиторий или устанавливать что-либо не нужно. Просто используйте npx @overpod/mcp-telegram.

Глобальная установка

npm install -g @overpod/mcp-telegram
mcp-telegram          # run server
mcp-telegram login    # QR login

Готовый бинарный файл (среда выполнения не требуется)

Скачайте файл в разделе Релизы — это автономные бинарные файлы, каждый в одном файле и без зависимостей:

Платформа	Сервер	CLI для входа
Linux x64	`mcp-telegram-linux-x64`	`mcp-telegram-login-linux-x64`
Linux ARM64	`mcp-telegram-linux-arm64`	`mcp-telegram-login-linux-arm64`
macOS x64	`mcp-telegram-darwin-x64`	`mcp-telegram-login-darwin-x64`
macOS ARM64	`mcp-telegram-darwin-arm64`	`mcp-telegram-login-darwin-arm64`
Windows x64	`mcp-telegram-windows-x64.exe`	`mcp-telegram-login-windows-x64.exe`

# Download (example for Linux x64)
curl -L -o mcp-telegram https://github.com/mcp-telegram/mcp-telegram/releases/latest/download/mcp-telegram-linux-x64
curl -L -o mcp-telegram-login https://github.com/mcp-telegram/mcp-telegram/releases/latest/download/mcp-telegram-login-linux-x64
chmod +x mcp-telegram mcp-telegram-login

# Login
TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH ./mcp-telegram-login

# Run
./mcp-telegram

Сборка из исходного кода

git clone https://github.com/mcp-telegram/mcp-telegram.git
cd mcp-telegram
npm install && npm run build

Docker

docker build -t mcp-telegram https://github.com/mcp-telegram/mcp-telegram.git

Выполните вход в интерактивном терминале:

docker run -it --rm \
  -e TELEGRAM_API_ID=YOUR_ID \
  -e TELEGRAM_API_HASH=YOUR_HASH \
  -v ~/.mcp-telegram:/root/.mcp-telegram \
  --entrypoint node mcp-telegram dist/qr-login-cli.js

Запустите MCP-сервер:

docker run -i --rm \
  -e TELEGRAM_API_ID=YOUR_ID \
  -e TELEGRAM_API_HASH=YOUR_HASH \
  -v ~/.mcp-telegram:/root/.mcp-telegram \
  mcp-telegram

Примечание: Войти нужно один раз через терминал. После этого сессия сохраняется в ~/.mcp-telegram и используется автоматически.

Использование с MCP-клиентами

Claude Code (CLI)

claude mcp add telegram -s user \
  -e TELEGRAM_API_ID=YOUR_ID \
  -e TELEGRAM_API_HASH=YOUR_HASH \
  -- npx @overpod/mcp-telegram

Claude Desktop

Откройте файл конфигурации:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Добавьте сервер Telegram:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["@overpod/mcp-telegram"],
      "env": {
        "TELEGRAM_API_ID": "YOUR_ID",
        "TELEGRAM_API_HASH": "YOUR_HASH"
      }
    }
  }
}

Перезапустите Claude Desktop.
Попросите Claude: «Запусти telegram-login» — появится QR-код. Если изображение не отображается, его копия будет сохранена в ~/.mcp-telegram/qr-login.png. Отсканируйте код в Telegram: Настройки > Устройства > Подключить устройство для компьютера.
Попросите Claude: «Запусти telegram-status», чтобы проверить подключение.

Примечание: Терминал не требуется — вход можно выполнить прямо через Claude Desktop.

Claude Desktop (бинарный файл)

Настройте подключение так же, но вместо npx используйте готовый бинарный файл:

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/mcp-telegram",
      "env": {
        "TELEGRAM_API_ID": "YOUR_ID",
        "TELEGRAM_API_HASH": "YOUR_HASH"
      }
    }
  }
}

Claude Desktop (Docker)

Сначала выполните вход через терминал (см. раздел Docker выше).
Добавьте следующую конфигурацию в файл настроек:

{
  "mcpServers": {
    "telegram": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "TELEGRAM_API_ID=YOUR_ID",
        "-e", "TELEGRAM_API_HASH=YOUR_HASH",
        "-v", "~/.mcp-telegram:/root/.mcp-telegram",
        "mcp-telegram"
      ]
    }
  }
}

Перезапустите Claude Desktop. Попросите Claude: «Запусти telegram-status», чтобы проверить подключение.

Cursor / VS Code

Добавьте приведённую выше конфигурацию JSON в настройки MCP: Cursor Settings > MCP или файл конфигурации MCP для VS Code.

Mastra

import { MCPClient } from "@mastra/mcp";

const telegramMcp = new MCPClient({
  id: "telegram-mcp",
  servers: {
    telegram: {
      command: "npx",
      args: ["@overpod/mcp-telegram"],
      env: {
        TELEGRAM_API_ID: process.env.TELEGRAM_API_ID!,
        TELEGRAM_API_HASH: process.env.TELEGRAM_API_HASH!,
      },
    },
  },
});

Инструменты

Все инструменты автоматически обнаруживаются через MCP. Подключённый AI-клиент получит полный список инструментов с параметрами и описаниями.

Категория	Инструменты
Аутентификация	`telegram-status`, `telegram-login`, `telegram-logout`
Сообщения	`telegram-send-message` (включая `quoteText` для дословного цитирования в ответе и `effect` для Premium-сообщений), `telegram-edit-message`, `telegram-delete-message`, `telegram-forward-message`, `telegram-send-scheduled`, `telegram-send-typing`, `telegram-translate-message`, `telegram-get-message-link`
Запланированные сообщения	`telegram-get-scheduled`, `telegram-delete-scheduled`
Чтение	`telegram-list-chats`, `telegram-read-messages`, `telegram-search-messages`, `telegram-search-global`, `telegram-search-chats`, `telegram-get-unread`, `telegram-mark-as-read`, `telegram-get-replies`, `telegram-get-unread-mentions`, `telegram-get-unread-reactions`, `telegram-get-saved-dialogs`
Черновики	`telegram-save-draft`, `telegram-get-drafts`, `telegram-clear-drafts`
Темы форума	`telegram-list-topics`, `telegram-read-topic-messages`, `telegram-create-topic`, `telegram-edit-topic`, `telegram-delete-topic`
Опросы	`telegram-create-poll`
Взаимодействие с опросами (v1.31.0)	`telegram-vote-poll`, `telegram-get-poll-results`, `telegram-get-poll-voters`, `telegram-close-poll`
Реакции	`telegram-send-reaction`, `telegram-get-reactions`, `telegram-set-default-reaction`, `telegram-get-top-reactions`, `telegram-get-recent-reactions`
Платные реакции (v1.31.0)	`telegram-send-paid-reaction` (★ Stars), `telegram-toggle-paid-reaction-privacy`, `telegram-get-paid-reaction-privacy`
Расшифровка аудио (v1.31.0)	`telegram-transcribe-audio` (Premium), `telegram-get-transcription`, `telegram-rate-transcription`
Проверка фактов (v1.31.0)	`telegram-get-fact-check`, `telegram-edit-fact-check`, `telegram-delete-fact-check`
Стикеры	`telegram-send-sticker`, `telegram-get-installed-stickers`, `telegram-get-recent-stickers`, `telegram-get-sticker-set`, `telegram-search-sticker-sets`
Медиа	`telegram-send-file`, `telegram-download-media`, `telegram-get-profile-photo`, `telegram-get-web-preview`
Отправка мультимедиа	`telegram-send-voice`, `telegram-send-video-note` (круглое видео), `telegram-send-location` (статическое или в реальном времени), `telegram-send-venue`, `telegram-send-contact`, `telegram-send-dice` (🎲🎯🎰🏀⚽🎳), `telegram-send-album` (от 2 до 10 фотографий или видео в одной группе)
Группы	`telegram-create-group`, `telegram-edit-group`, `telegram-invite-to-group`, `telegram-join-chat`, `telegram-leave-group`, `telegram-kick-user`, `telegram-ban-user`, `telegram-unban-user`, `telegram-set-admin`, `telegram-remove-admin`, `telegram-get-my-role`, `telegram-set-chat-permissions`, `telegram-set-slow-mode`, `telegram-get-admin-log`
Информация о чатах	`telegram-get-chat-info`, `telegram-get-chat-members`, `telegram-get-chat-folders`
Папки (v1.33.0)	`telegram-create-folder`, `telegram-edit-folder`, `telegram-delete-folder`, `telegram-reorder-folders`, `telegram-get-suggested-folders`, `telegram-toggle-folder-tags`
Глобальные настройки конфиденциальности (v1.33.0)	`telegram-get-global-privacy-settings`, `telegram-set-global-privacy-settings`
Пригласительные ссылки	`telegram-create-invite-link`, `telegram-get-invite-links`, `telegram-revoke-invite-link`
Контакты	`telegram-get-contacts`, `telegram-add-contact`, `telegram-get-contact-requests`
Модерация	`telegram-block-user`, `telegram-unblock-user`, `telegram-report-spam`
Профили (чтение)	`telegram-get-profile`, `telegram-update-profile`
Профиль (изменение, v1.32.0)	`telegram-set-emoji-status` (Premium), `telegram-list-emoji-statuses`, `telegram-clear-recent-emoji-statuses`, `telegram-set-profile-color` (Premium), `telegram-set-birthday`, `telegram-set-personal-channel`, `telegram-set-profile-photo`, `telegram-delete-profile-photo`
Аккаунт	`telegram-get-sessions`, `telegram-terminate-session`, `telegram-set-privacy`, `telegram-set-auto-delete`
Закрепление	`telegram-pin-message`, `telegram-unpin-message`
Настройки чата	`telegram-mute-chat`, `telegram-archive-chat`, `telegram-pin-chat`, `telegram-mark-dialog-unread`
Настройки администрирования	`telegram-toggle-channel-signatures`, `telegram-toggle-anti-spam`, `telegram-toggle-forum-mode`, `telegram-toggle-prehistory-hidden`, `telegram-set-chat-reactions`, `telegram-approve-join-request`
Статистика	`telegram-get-broadcast-stats`, `telegram-get-megagroup-stats`
Inline-боты и кнопки	`telegram-inline-query`, `telegram-inline-query-send`, `telegram-press-button`, `telegram-get-message-buttons`
Опрос в реальном времени	`telegram-get-state`, `telegram-get-updates`, `telegram-get-channel-updates`
Истории (чтение)	`telegram-get-all-stories`, `telegram-get-peer-stories`, `telegram-get-stories-by-id`, `telegram-get-story-views`
Истории (изменение, v1.30.0)	`telegram-send-story`, `telegram-edit-story`, `telegram-delete-stories`, `telegram-react-to-story`, `telegram-export-story-link`, `telegram-read-stories`, `telegram-toggle-story-pinned`, `telegram-toggle-story-pinned-to-top`, `telegram-activate-stealth-mode` (Premium), `telegram-get-stories-archive`, `telegram-report-story`
Обсуждение (v1.30.0)	`telegram-get-discussion-message`, `telegram-get-groups-for-discussion`
Отчёты о прочтении (v1.30.0)	`telegram-get-message-read-participants`, `telegram-get-outbox-read-date`
Бусты	`telegram-get-my-boosts`, `telegram-get-boosts-status`, `telegram-get-boosts-list`
Бизнес (v1.32.0)	`telegram-get-business-chat-links`, `telegram-create-business-chat-link`, `telegram-edit-business-chat-link`, `telegram-delete-business-chat-link`, `telegram-resolve-business-chat-link`, `telegram-set-business-hours`, `telegram-set-business-location`, `telegram-set-business-greeting`, `telegram-set-business-away`, `telegram-set-business-intro`
Подключаемые инструменты (управляются переменными окружения)	`telegram-get-group-call`, `telegram-get-group-call-participants` (требуется `MCP_TELEGRAM_ENABLE_GROUP_CALLS=1`); Stars и подарки: `telegram-get-stars-status`, `telegram-get-stars-transactions`, `telegram-get-stars-topup-options`, `telegram-get-stars-subscriptions`, `telegram-change-stars-subscription`, `telegram-get-available-star-gifts`, `telegram-get-saved-star-gifts`, `telegram-save-star-gift`, `telegram-convert-star-gift` (требуется `MCP_TELEGRAM_ENABLE_STARS=1`); `telegram-get-quick-replies`, `telegram-get-quick-reply-messages` (требуется `MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1`)

Совет: спросите у AI-ассистента: «Какие инструменты Telegram доступны?» — он предоставит полный список с параметрами и описаниями.

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

Некоторые инструменты по умолчанию отключены. Чтобы включить их, задайте соответствующие переменные окружения:

Переменная	Значение	Включаемые инструменты
`MCP_TELEGRAM_ENABLE_GROUP_CALLS`	`1`	`telegram-get-group-call`, `telegram-get-group-call-participants`
`MCP_TELEGRAM_ENABLE_STARS`	`1`	Баланс и история транзакций Stars, варианты пополнения, подписки и подарки Star Gifts (просмотр / сохранение / конвертация)
`MCP_TELEGRAM_ENABLE_QUICK_REPLIES`	`1`	`telegram-get-quick-replies`, `telegram-get-quick-reply-messages`

Чтобы включить эти возможности, добавьте переменные в файл .env или конфигурацию MCP-клиента.

Разработка

npm run dev        # Start with file watching (tsx)
npm start          # Start the MCP server
npm run login      # QR code login in terminal
npm run build      # Compile TypeScript
npm run lint       # Check code with Biome
npm run lint:fix   # Auto-fix lint issues
npm run format     # Format code with Biome

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

src/
  index.ts            -- MCP server entry point
  telegram-client.ts  -- TelegramService class (GramJS wrapper)
  qr-login-cli.ts     -- CLI utility for QR code login
  tools/              -- Modular tool definitions
    auth.ts           -- Connection & login
    messages.ts       -- Send, read, search, edit, delete, forward; inline bots; real-time polling
    chats.ts          -- Chat listing, group management, admin toggles, stats
    contacts.ts       -- Contacts, profiles, moderation
    media.ts          -- Files, photos, downloads
    reactions.ts      -- Reactions, set-chat-reactions
    extras.ts         -- Pin, schedule, polls, topics
    stickers.ts       -- Sticker sets, send, search, browse
    account.ts        -- Sessions, privacy, auto-delete, profile, emoji status, birthday, chat mute/folders, invite links
    business.ts       -- Telegram Business: chat links CRUD, work hours, location, greeting/away/intro
    boosts.ts         -- Boost status, my boosts, boosters list
    stories.ts        -- Stories: list all, peer, by-id, view stats
    group-calls.ts    -- Group call info and participants (opt-in: MCP_TELEGRAM_ENABLE_GROUP_CALLS)
    stars.ts          -- Stars wallet status and transactions (opt-in: MCP_TELEGRAM_ENABLE_STARS)
    quick-replies.ts  -- Quick replies and messages (opt-in: MCP_TELEGRAM_ENABLE_QUICK_REPLIES)
    shared.ts         -- Shared utilities

Технологический стек

TypeScript -- модули ES2022 и ESM
GramJS (telegram) -- клиент Telegram для MTProto
@modelcontextprotocol/sdk -- фреймворк для MCP-серверов
Zod -- проверка схем параметров инструментов во время выполнения
Biome -- линтер и форматтер
tsx -- запуск TypeScript без этапа сборки
dotenv -- управление переменными окружения

Решение проблем

AUTH_KEY_DUPLICATED

Сеанс Telegram можно использовать только в одном процессе одновременно. Ошибка AUTH_KEY_DUPLICATED означает, что этот файл сеанса уже используется другим процессом.

Решение: создайте отдельные сеансы для каждой среды:

# Local development
TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-local npx @overpod/mcp-telegram login

# Production server
TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-prod npx @overpod/mcp-telegram login

Затем укажите соответствующий TELEGRAM_SESSION_PATH в конфигурации MCP каждой среды.

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

Данные API для аутентификации хранятся в .env (исключён из Git)
Сеанс хранится в ~/.mcp-telegram/session с разрешениями 0600 (доступ только владельцу)
Каталог сеанса создаётся с разрешениями 0700
Номер телефона не требуется — аутентификация выполняется только через QR-код
Данные не передаются сторонним сервисам: всё взаимодействие с серверами Telegram происходит напрямую через MTProto
QR-коды для входа создаются локально и не покидают ваш компьютер
Один сеанс на процесс — одновременное использование одного сеанса в нескольких процессах приводит к ошибке AUTH_KEY_DUPLICATED (см. раздел «Решение проблем»)
Это юзербот (личный аккаунт), а не бот. Соблюдайте Условия использования Telegram

Лицензия

MIT