mcp-telegram-notify

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

Возможности

• Транспорты: stdio, http (Streamable HTTP), sse (legacy)

• Напоминания переживают рестарт (SQLite + фоновый worker)

• Health-check: GET /health

• Опционально: ngrok для публичного HTTPS

Related MCP server: tgfmcp

Требования

• 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

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

Полный список — в .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).

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

Лицензия

MIT — см. LICENSE.