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
• (Опционально) Docker / Docker Compose

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

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

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

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

python -m venv .venv

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

# Linux / macOS
source .venv/bin/activate

pip install -r requirements.txt

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

cp .env.example .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. Откройте в браузере:

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

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

6. Запуск

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

fastmcp dev server.py

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

python server.py

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

MCP_TRANSPORT=http
MCP_HOST=127.0.0.1
MCP_PORT=8000

python server.py

Проверка:

curl http://127.0.0.1:8000/health

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

Добавьте в ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.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 обычно:

ABSOLUTE_PATH_TO_PROJECT/.venv/bin/python

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

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

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

Docker

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:

NGROK_AUTHTOKEN=your_ngrok_token

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

docker compose up -d --build

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

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

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

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.

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

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.