# 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-сервера.

## Архитектура

```text
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`

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

```text
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`

## Установка

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

```bash
git clone <repository-url>
cd telegram-mcp
```

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

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

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

```bash
pip install -r requirements.txt
```

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

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

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

```bash
cp .env.example .env
```

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

```dotenv
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` после того, как бот получил сообщение из нужного чата.

## Запуск

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

```bash
python src/server.py
```

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

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

```bash
mcp dev src/server.py
```

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

## MCP tools

### `send_message`

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

Параметры:

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

Пример:

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

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

### `get_recent_messages`

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

Параметры:

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

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

Пример:

```text
chat_id: 123456789
limit: 10
```

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

### `get_chat_info`

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

Параметры:

```text
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.