Skip to main content
Glama
deenesjakoruzh
Steph-ux

telegram-mcp-server

by Steph-ux
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

telegram-mcp-server

Telegram MCP-сервер на базе Telethon — постоянный клиент, устойчивый к флуду, 9 сгруппированных инструментов.

Никаких API-ключей в коде. Файлы сессий хранятся локально. Работает с пользовательскими аккаунтами (2FA) и ботами.

1. Установка

git clone <this-repo> telegram-mcp-server
cd telegram-mcp-server

python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

pip install -e .

Получите свои учётные данные API

  1. Перейдите на my.telegram.org

  2. Войдите со своим номером телефона

  3. Создайте приложение → получите API ID и API Hash

Разовая авторизация

# User account (with 2FA support)
export TG_API_ID=12345
export TG_API_HASH="your_hash_here"
telegram-mcp-server --auth --phone +33612345678

# Or via MCP tool: tg_session(action="auth", api_id=12345, api_hash="...", phone="+33612345678")

Related MCP server: telegram-mcp

2. Регистрация в вашем MCP-клиенте

Claude Desktop / OpenCode

{
  "mcpServers": {
    "telegram": {
      "command": "telegram-mcp-server",
      "env": {
        "TG_API_ID": "12345",
        "TG_API_HASH": "your_hash_here"
      }
    }
  }
}

Если не в PATH:

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "telegram_mcp_server"],
      "env": {
        "TG_API_ID": "12345",
        "TG_API_HASH": "your_hash_here"
      }
    }
  }
}

Docker

docker build -t telegram-mcp .
docker run -i --rm \
  -v ~/.telegram-mcp/sessions:/root/.telegram-mcp/sessions \
  -e TG_API_ID=12345 \
  -e TG_API_HASH="your_hash" \
  telegram-mcp

3. Каталог инструментов (9 инструментов, 8 действий)

tg_session — Управление сессиями

действие

Обязательные аргументы

Описание

auth

api_id, api_hash, phone или bot_token

Аутентифицироваться (поддерживается 2FA)

check

—

Проверить статус входа

logout

—

Удалить сессию

tg_message — Отправка, пересылка, удаление, ответ

действие

Обязательные аргументы

Описание

send

target, text

Отправить сообщение

forward

target, message_id, to_target

Переслать сообщение

delete

target, message_id

Удалить сообщение

reply

target, message_id, text

Ответить на сообщение

tg_chat — Операции с чатом

действие

Обязательные аргументы

Описание

list

—

Показать недавние чаты

info

target

Получить информацию о чате

members

target

Перечислить участников чата

leave

target

Покинуть чат

tg_search — Поиск

действие

Обязательные аргументы

Описание

messages

query

Искать сообщения (опционально в target)

users

query

Искать контакты/пользователей

channels

query

Искать каналы

tg_history — История чата

действие

Обязательные аргументы

Описание

messages

target

Получить историю сообщений

media

target

Получить историю только с медиа

files

target

Получить историю только с файлами

tg_user — Операции с пользователем

действие

Обязательные аргументы

Описание

me

—

Получить информацию о себе

info

target

Получить информацию о пользователе

block

target

Заблокировать пользователя

unblock

target

Разблокировать пользователя

tg_media — Отправка медиа

действие

Обязательные аргументы

Описание

send_photo

target, file_path

Отправить фото

send_video

target, file_path

Отправить видео

send_file

target, file_path

Отправить документ

send_voice

target, file_path

Отправить голосовое сообщение

tg_channel — Управление каналом

действие

Обязательные аргументы

Описание

create

title

Создать супергруппу/канал

join

target

Вступить в канал

leave

target

Покинуть канал

info

target

Получить информацию о канале

tg_draft — Черновики сообщений

действие

Обязательные аргументы

Описание

save

target, text

Сохранить черновик

list

—

Показать все черновики

delete

target

Удалить черновик

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

Переменная

По умолчанию

Описание

TG_API_ID

0

Telegram API ID (с my.telegram.org)

TG_API_HASH

""

Telegram API Hash

TG_SESSION_DIR

~/.telegram-mcp/sessions

Расположение файлов сессий

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

  • Ограничитель частоты запросов: действия отправки — не более 5 в минуту; действия чтения — без ограничений.

  • Автоповтор при FloodWaitError: выжидает необходимое время (не более 5 минут).

  • Файлы сессий: только локально, никогда не попадают в git.

  • Поддержка 2FA: полная поддержка аккаунтов с двухфакторной аутентификацией.

6. MCP-ресурсы

  • tg://version — Версия сервера

  • tg://session/status — Статус авторизации

Лицензия

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • tdlib-mcp-server

    Crocodile-beep
    F
    license
    Not graded
    quality
    D
    maintenance
    Connects AI agents to Telegram via the official TDLib library, enabling tools like getting user info, listing dialogs, and searching messages.
    -

  • telegram-mcp

    chenzhaoxuan0
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables interaction with Telegram Bot API for sending messages, photos, editing messages, answering callbacks, and fetching updates.
    MIT

  • telegram-mcp

    Shaan-alpha
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to interact with a user's Telegram account: list chats, read history, search, and send messages through Telegram's MTProto API.
    1
    MIT