# mcp-telegram-notify

MCP-сервер для **уведомлений и напоминаний в Telegram**.  
Работает с Cursor, Claude Desktop и другими MCP-клиентами. Можно запускать локально (stdio) или в Docker (HTTP).

## Возможности

| Tool | Описание |
|------|----------|
| `send_telegram_message` | Мгновенная отправка текста в чат |
| `schedule_telegram_reminder` | Отложенная отправка через N секунд (хранит задачи в SQLite) |

- Транспорты: `stdio`, `http` (Streamable HTTP), `sse` (legacy)
- Напоминания переживают рестарт (SQLite + фоновый worker)
- Health-check: `GET /health`
- Опционально: ngrok для публичного HTTPS

## Требования

- Python **3.12+**
- Telegram-бот и токен от [@BotFather](https://t.me/BotFather)
- (Опционально) Docker / Docker Compose

## Быстрый старт (локально)

### 1. Клонируйте репозиторий

```bash
git clone https://github.com/<your-username>/mcp-telegram-notify.git
cd mcp-telegram-notify
```

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

```bash
python -m venv .venv

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

# Linux / macOS
source .venv/bin/activate

pip install -r requirements.txt
```

### 3. Настройте `.env`

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

Откройте `.env` и укажите токен:

```env
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
MCP_TRANSPORT=stdio
LOG_LEVEL=INFO
```

### 4. Напишите боту `/start`

В Telegram откройте своего бота и отправьте `/start`.  
Без этого `sendMessage` вернёт ошибку 403.

### 5. Узнайте свой `chat_id`

1. Напишите боту любое сообщение.
2. Откройте в браузере:

```text
https://api.telegram.org/bot<ВАШ_ТОКЕН>/getUpdates
```

3. Найдите `"chat":{"id": ...}` — это ваш `chat_id`.

### 6. Запуск

**Режим разработки (Inspector):**

```bash
fastmcp dev server.py
```

**Обычный STDIO (для Cursor / Claude Desktop):**

```bash
python server.py
```

**HTTP-режим (порт 8000):**

```env
MCP_TRANSPORT=http
MCP_HOST=127.0.0.1
MCP_PORT=8000
```

```bash
python server.py
```

Проверка:

```bash
curl http://127.0.0.1:8000/health
```

## Подключение в Cursor

Добавьте в `~/.cursor/mcp.json` (Windows: `%USERPROFILE%\.cursor\mcp.json`):

```json
{
  "mcpServers": {
    "telegram": {
      "command": "ABSOLUTE_PATH_TO_PROJECT/.venv/Scripts/python.exe",
      "args": ["ABSOLUTE_PATH_TO_PROJECT/server.py"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_bot_token_here",
        "MCP_TRANSPORT": "stdio",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}
```

На Linux/macOS путь к Python обычно:

```text
ABSOLUTE_PATH_TO_PROJECT/.venv/bin/python
```

После сохранения: **Cursor → Settings → MCP → Reload**.

Пример запроса в чате Cursor:

> Отправь мне в Telegram через MCP сообщение «Привет!» на chat_id `123456789`

## Docker

```bash
cp .env.example .env
# Заполните TELEGRAM_BOT_TOKEN
# Для Docker оставьте MCP_TRANSPORT=http

docker compose up -d --build
docker compose logs -f telegram-mcp
```

- MCP: `http://localhost:8000/mcp`
- Health: `http://localhost:8000/health`
- SQLite сохраняется в `./data` (том Docker)

### ngrok (публичный HTTPS)

1. Получите токен: https://dashboard.ngrok.com/get-started/your-authtoken  
2. Добавьте в `.env`:

```env
NGROK_AUTHTOKEN=your_ngrok_token
```

3. Запустите:

```bash
docker compose up -d --build
```

4. Узнайте публичный URL:

- браузер: http://localhost:4040  
- или логи: `docker compose logs ngrok`

Endpoint для внешних шлюзов (например Zuplo):

```text
https://<subdomain>.ngrok-free.app/mcp
```

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

| Переменная | Описание | По умолчанию |
|------------|----------|--------------|
| `TELEGRAM_BOT_TOKEN` | Токен бота | **обязательно** |
| `MCP_TRANSPORT` | `stdio` / `http` / `sse` | `stdio` (в Docker — `http`) |
| `MCP_HOST` / `MCP_PORT` | Хост и порт HTTP | `0.0.0.0` / `8000` |
| `MCP_PATH` | Путь MCP endpoint | `/mcp` |
| `REMINDERS_DB_PATH` | Путь к SQLite | `reminders.db` |
| `REMINDER_POLL_INTERVAL_SECONDS` | Интервал worker | `5` |
| `REMINDER_MIN/MAX_DELAY_SECONDS` | Лимиты задержки | `1` / `2592000` |
| `LOG_LEVEL` | Уровень логов | `INFO` |
| `NGROK_AUTHTOKEN` | Токен ngrok | опционально |
| `ENABLE_X402_MIDDLEWARE` | Stub монетизации | `false` |

Полный список — в [`.env.example`](.env.example).

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

```text
mcp-telegram-notify/
├── server.py             # MCP-сервер, tools, SQLite, worker
├── requirements.txt
├── .env.example
├── Dockerfile
├── docker-compose.yml
├── .gitignore
├── .dockerignore
├── LICENSE
└── README.md
```

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

- **Не коммитьте** `.env`, токены бота и ngrok.
- Файл `.env` уже в `.gitignore`.
- Токен бота даёт полный доступ к боту — храните его как секрет.
- Если токен засветился — перевыпустите через @BotFather (`/revoke`).

## Устранение неполадок

| Симптом | Что проверить |
|---------|----------------|
| `403 Forbidden` | Напишите боту `/start` |
| `401 Unauthorized` | Неверный `TELEGRAM_BOT_TOKEN` |
| Cursor не видит tools | Reload MCP, путь к Python/venv |
| Напоминание не пришло | Смотрите логи; worker опрашивает БД каждые 5–10 сек |
| Docker `/health` падает | Дождитесь `start_period`, проверьте `docker compose logs` |

## Лицензия

MIT — см. [LICENSE](LICENSE).