MCP 服务器

mcp-telegram-notify

MCP server for sending Telegram messages and scheduling reminders, supporting multiple transports and Docker deployment.

README

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`

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

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

Найдите "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)

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

NGROK_AUTHTOKEN=your_ngrok_token

Запустите:

docker compose up -d --build

Узнайте публичный 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`