# telegram-mcp-http

**Telegram MCP-сервер (MTProto / Telethon) с HTTP-транспортом** — разворачивается на Railway за ~5 минут, каждый пользователь работает со **своим** Telegram-аккаунтом.

В репозитории **нет никаких ключей и токенов** — все данные подключаются через переменные окружения на Railway.

## Что умеет (6 инструментов)

| Инструмент | Что делает |
|---|---|
| `telegram_get_me` | Кто я в Telegram |
| `telegram_list_chats` | Список всех чатов/каналов/групп |
| `telegram_get_messages` | История сообщений чата |
| `telegram_search_messages` | Поиск по всем чатам |
| `telegram_send_message` | Отправка сообщения |
| `telegram_get_contacts` | Контакты аккаунта |

## Установка за 5 шагов

### Шаг 1. Получите api_id / api_hash (2 мин)
1. Откройте [my.telegram.org](https://my.telegram.org) → войдите по своему номеру
2. **API development tools** → создайте приложение (название любое)
3. Скопируйте **api_id** (число) и **api_hash** (строка)

### Шаг 2. Сгенерируйте строку сессии (2 мин)
На своём компьютере (нужен Python 3.9+):

```bash
pip install telethon
python generate_session.py
```

Введите api_id, api_hash, телефон и код подтверждения из Telegram. Скрипт напечатает `TG_SESSION_STRING` — скопируйте её.

> ⚠️ Строка сессии = полный доступ к вашему аккаунту. Не публикуйте её нигде.

### Шаг 3. Разверните на Railway (1 мин)
1. Сделайте **Fork** этого репозитория себе на GitHub
2. [railway.com](https://railway.com) → **New Project** → **Deploy from GitHub repo** → выберите свой форк
3. В сервисе: **Variables** → добавьте три переменные:
   - `TG_API_ID`
   - `TG_API_HASH`
   - `TG_SESSION_STRING`
4. **Settings** → **Networking** → **Generate Domain**

### Шаг 4. Проверка
Откройте `https://ВАШ-ДОМЕН.up.railway.app/health`

Должно быть: `"status": "ok"`, `"telegram_connected": true` и все `"config": true`.

### Шаг 5. Подключите к своему ИИ-клиенту

```json
{
  "mcpServers": {
    "telegram": {
      "url": "https://ВАШ-ДОМЕН.up.railway.app/mcp",
      "type": "http"
    }
  }
}
```

## Частые проблемы

| Симптом | Причина | Решение |
|---|---|---|
| `/health` → `config: false` | Не заданы переменные | Variables на Railway → задать → передеплой |
| `telegram_connected: false` | Неверная сессия или api_hash | Перегенерируйте `TG_SESSION_STRING` |
| Клиент MCP не подключается | Кеш старого деплоя | Railway → Deployments → Redeploy |

## Безопасность
- Каждому — свой форк и свой Railway-проект. Делить одну сессию на нескольких людей **нельзя** (Telegram разорвёт сессии).
- Строка сессии хранится только в Variables вашего Railway-аккаунта.
- Для отзыва доступа: Telegram → Настройки → Устройства → завершить сеанс, затем сгенерируйте новую строку.