Telegram MCP Server

MCP-сервер для взаимодействия с Telegram через Telegram Bot API. Сервер предоставляет LLM-клиенту набор инструментов для отправки сообщений, чтения последних доступных сообщений и получения информации о чате.

Возможности

Сервер предоставляет три MCP tools:

• send_message — отправляет текстовое сообщение в указанный Telegram-чат.
• get_recent_messages — получает последние доступные сообщения из указанного чата.
• get_chat_info — возвращает основную информацию о Telegram-чате.

Сервер использует stdio transport, поэтому его можно подключать к MCP Inspector и другим MCP-клиентам без отдельного HTTP-сервера.

Архитектура

MCP client / MCP Inspector
            │
            │ MCP over stdio
            ▼
      src/server.py
            │
            ▼
   src/telegram_client.py
            │
            │ HTTPS
            ▼
    Telegram Bot API

server.py отвечает за MCP-интерфейс и регистрацию tools.

telegram_client.py инкапсулирует HTTP-взаимодействие с Telegram Bot API.

config.py загружает токен из переменной окружения.

Стек

• Python 3.10+
• MCP Python SDK 2.x
• Telegram Bot API
• httpx
• python-dotenv

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

telegram-mcp/
├── src/
│   ├── __init__.py
│   ├── config.py
│   ├── telegram_client.py
│   └── server.py
├── .env.example
├── .gitignore
├── requirements.txt
└── README.md

Требования

• Python 3.10 или новее
• Telegram-бот, созданный через @BotFather
• Node.js и npx — только если используется MCP Inspector через mcp dev

Установка

Клонируйте репозиторий и перейдите в его директорию:

git clone <repository-url>
cd telegram-mcp

Создайте виртуальное окружение:

python3 -m venv .venv
source .venv/bin/activate

Установите зависимости:

pip install -r requirements.txt

Настройка Telegram-бота

1. Откройте Telegram и найдите @BotFather.
2. Выполните /newbot.
3. Создайте бота и получите Bot API token.
4. Не добавляйте токен в исходный код или Git.

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

cp .env.example .env

Укажите токен:

TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here

.env добавлен в .gitignore.

Подготовка чата

Личный чат

1. Откройте созданного бота.
2. Нажмите Start или отправьте ему сообщение.
3. Для проверки get_recent_messages отправьте несколько текстовых сообщений.

Группа

1. Создайте тестовую группу.
2. Добавьте в неё бота.
3. Если бот должен видеть обычные сообщения группы, отключите для него режим приватности через @BotFather (/setprivacy → Disable).
4. Отправьте в группу несколько сообщений.

Для получения chat_id удобно сначала вызвать get_chat_info или get_recent_messages после того, как бот получил сообщение из нужного чата.

Запуск

Из корневой директории проекта:

python src/server.py

Сервер работает через stdio и ожидает MCP-соединение. Поэтому отсутствие обычного вывода в терминал после запуска является нормальным поведением.

Для разработки и проверки можно использовать MCP CLI:

mcp dev src/server.py

Команда запускает сервер и MCP Inspector. Inspector использует npx, поэтому Node.js должен быть доступен в PATH.

MCP tools

send_message

Отправляет текстовое сообщение в Telegram.

Параметры:

chat_id: string — ID чата
text: string — текст сообщения

Пример:

chat_id: 123456789
text: Привет! Сообщение отправлено через MCP.

В ответ сервер возвращает подтверждение отправки и message_id.

get_recent_messages

Получает последние доступные сообщения указанного чата.

Параметры:

chat_id: string — ID чата
limit: integer — количество сообщений, по умолчанию 10

limit ограничивается диапазоном от 1 до 100.

Пример:

chat_id: 123456789
limit: 10

Результат содержит отправителя и текст каждого доступного сообщения.

get_chat_info

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

Параметры:

chat_id: string — ID чата

В ответе отображаются доступные поля, включая ID, тип, название, username, имя и фамилию.

Как работает получение сообщений

Telegram Bot API не предоставляет боту отдельный метод для чтения произвольной истории чата. Для получения входящих сообщений сервер использует getUpdates.

get_recent_messages запрашивает до 100 последних доступных updates и затем фильтрует их по chat_id. Поэтому инструмент работает с сообщениями, которые Telegram предоставляет боту через очередь updates, а не с полной историей чата.

Это означает, что tool не является заменой Telegram-клиенту с доступом ко всей истории переписки. Для тестирования достаточно отправить сообщения после добавления бота в чат и затем вызвать get_recent_messages.

Важно: getUpdates не используется одновременно с активным webhook. Если для бота настроен webhook, сначала удалите его, чтобы long polling через getUpdates мог получать updates.

Пример сценария

1. Запустить MCP Inspector.
2. Подключить src/server.py.
3. Убедиться, что доступны:
   • send_message
   • get_recent_messages
   • get_chat_info
4. Вызвать get_chat_info для проверки подключения к чату.
5. Вызвать send_message и убедиться, что сообщение появилось в Telegram.
6. Отправить несколько сообщений в Telegram.
7. Вызвать get_recent_messages и проверить полученный список сообщений.

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

Telegram Bot API token передаётся только через переменную окружения TELEGRAM_BOT_TOKEN.

Настоящий .env не должен попадать в Git. В репозитории хранится только .env.example без рабочего токена.

Ограничения

• Бот не имеет доступа ко всей истории Telegram-чата через Bot API.
• get_recent_messages работает с доступными bot updates.
• В группах набор сообщений, которые бот получает, зависит от настроек приватности Telegram.
• getUpdates и webhook являются взаимоисключающими способами получения updates.