This server lets MCP clients send notifications to a configured channel (Telegram bot or local file) and track their delivery status.
Queue a notification via notify with a message, event type (info, action_required, review_requested, error), optional title, source, URL, and idempotency key.
Check delivery status via notification_status — returns queued, sending, sent, or failed with retry details and timestamps.
Run in stdio mode (managed by an MCP client like Codex) or as a background HTTP server for multiple clients.
Configure recipients and channels (Telegram or local file) through server settings or MCP client env.
Survives restarts with SQLite queue and automatic retries for transient errors.
Send test notifications and manage the background HTTP server with CLI commands (start, stop, restart, status, logs, test).
Allows sending notifications via the Telegram Bot API to a configured chat, with support for binding a chat through /start and receiving notification delivery confirmations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@notification-mcp Send a Telegram notification that the nightly backup completed successfully."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Уведомления из MCP-клиента — в выбранный вами канал. Агент сообщает, что работа готова, нужно решение или возникла ошибка. Сервер выбирает получателя и доставляет сообщение.
Сейчас доступны Telegram-бот и локальный файл для проверки без интернета. Инструменты
notify и notification_status общие для всех каналов. Поддерживаются Streamable HTTP и stdio.
Рекомендуемый режим — stdio. Codex сам запускает локальный сервер при подключении и завершает
его вместе с MCP-соединением. Отдельные start и stop не нужны.
Нужен uv — он установит подходящий Python и зависимости автоматически. Если uv ещё нет, выполните один раз:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"После публикации релиза установите зафиксированную версию из GitHub:
uv tool install --python 3.11 "git+https://github.com/IndyukovAnton/notification-mcp.git@v0.4.0"
uv tool update-shellОткройте новый терминал. Для установки по Git URL требуется Git. Без него скачайте wheel со страницы GitHub Release и выполните:
uv tool install --python 3.11 .\notification_mcp_relay-0.4.0-py3-none-any.whlВ GitHub нажмите Code → Download ZIP, распакуйте архив и откройте терминал в этой папке. На Windows:
powershell -ExecutionPolicy Bypass -File .\install.ps1На Linux и macOS:
uv tool install --python 3.11 .
uv tool update-shellСоздайте бота через @BotFather, затем выполните одну команду:
notification-mcp connect codex --token-envКоманда скрыто запросит токен и сохранит его как пару TELEGRAM_BOT_TOKEN = значение
непосредственно в локальной записи MCP-сервера. Системная переменная ОС и отдельный
config.toml не создаются.
Перезапустите Codex и проверьте /mcp: сервер notifications должен быть активен. Затем откройте
личный чат со своим ботом, отправьте /start и дождитесь ответа
«Чат подключён. Новые уведомления будут приходить сюда».
Первый пользователь с /start становится владельцем привязки — выполните этот шаг сами.
После перезапуска токен и чат вводить заново не нужно.
Уже пользовались предыдущей версией? Сначала прочитайте как перенести существующие настройки и очередь.
Любой локальный MCP-клиент должен запускать один и тот же executable без аргументов и передавать
токен в собственном объекте env. Для JSON-конфигураций:
{
"mcpServers": {
"notifications": {
"command": "notification-mcp",
"env": {
"TELEGRAM_BOT_TOKEN": "ТОКЕН_ОТ_BOTFATHER"
}
}
}
}Эквивалент для Codex:
[mcp_servers.notifications]
command = "notification-mcp"
[mcp_servers.notifications.env]
TELEGRAM_BOT_TOKEN = "ТОКЕН_ОТ_BOTFATHER"Если приложение не видит notification-mcp через PATH, укажите полный путь к установленному
launcher. Сервер принимает те же поля command, args и env, что и обычные stdio MCP-серверы.
Готовый JSON с безопасным placeholder выдаёт notification-mcp client-config json --token-env.
Для нескольких каналов и собственной маршрутизации остаётся расширенный режим с config.toml.
Напишите агенту в Codex:
Вызови notify сервера notifications: сообщение «Проверка подключения», событие info. Затем проверь доставку через notification_status.
Ожидаются уведомление в Telegram и состояние sent. В дальнейших задачах достаточно поручения:
По завершении работы отправь через notifications уведомление с событием review_requested. Кратко напиши, что сделано и что мне проверить.
MCP-клиент должен сам вызвать инструмент: сервер не следит за ходом работы агента. Постоянное правило для Codex приведено в инструкции подключения.
Related MCP server: notify-hub
Используйте его, если один сервер должен одновременно обслуживать несколько MCP-клиентов:
notification-mcp setup
notification-mcp start
notification-mcp connect codex --transport http
notification-mcp testВ HTTP-режиме терминал можно закрыть, но после перезагрузки компьютера нужно снова выполнить
notification-mcp start. Для другого клиента используйте http://127.0.0.1:8765/mcp или
готовый JSON из notification-mcp client-config.
Команда | Действие |
| Запустить фоновый HTTP-сервер |
| Завершить текущую попытку отправки и остановить сервер |
| Перезапустить и применить изменённые настройки |
| Показать состояние фонового сервера, адрес и пути файлов |
| Показать последние сообщения сервера |
| Отправить проверочное уведомление и дождаться результата |
start/stop/status не управляют stdio-процессом: его жизненным циклом управляет MCP-клиент.
ОС | Конфигурация по умолчанию |
Windows |
|
Linux |
|
macOS |
|
Рядом сохраняются очередь и привязка Telegram; фоновый HTTP-режим также сохраняет журнал.
В рекомендуемом stdio-режиме токен хранится в локальной настройке самого MCP-клиента в поле
env; отдельная системная переменная и сервисный TOML не нужны. Как и у других локальных
MCP-серверов, этот секрет хранится открытым текстом в конфигурации выбранного клиента.
Для обновления закройте Codex, остановите HTTP-сервер, если он используется, и установите новый
тег с --force. Например:
notification-mcp stop
uv tool install --python 3.11 --force "git+https://github.com/IndyukovAnton/notification-mcp.git@v0.4.0"setup повторять не нужно. Для удаления закройте Codex и выполните:
codex mcp remove notifications
notification-mcp stop
uv tool uninstall notification-mcp-relayЛичные настройки и история при удалении программы сохраняются.
notify сохраняет сообщение в SQLite и возвращает ID. queued означает принятие в очередь.
Временные ошибки соединения повторяются с увеличением задержки; очередь переживает перезапуск.
notification_status показывает queued, sending, sent или failed.
sent означает подтверждение канала доставки, а не прочтение человеком.
Получатель фиксируется при постановке в очередь. Смена чата влияет на новые уведомления.
После исчерпания попыток сообщение получает failed. При неоднозначном сетевом сбое возможен дубль.
MCP-клиент должен сам вызвать инструмент: сервер не следит за ходом работы агента. Локальный адрес доступен приложениям на этом компьютере. Для удалённого облачного клиента потребуется отдельное развёртывание с защищённым доступом; текущий HTTP-сервер слушает только localhost.
Используются официальный Python MCP SDK и Telegram Bot API. Подход к MCP взят из того же SDK, что и у chigwell/telegram-mcp; его исходники не копировались, Telethon и пользовательские Telegram-сессии не используются.
MIT License. Бесплатное использование, изменение и распространение разрешены при сохранении copyright-уведомления и текста лицензии. Автор: Anton Indyukov.
Read queued/sending/sent/failed status. 'sent' does not confirm the user read it.
Inputs: notification_id (required). Returns: id, event, status, channel, +7 more
Queue a notification. Delivery channel and recipient are chosen by server settings.
event: info, action_required (needs a decision), review_requested (ready to inspect), or error. source identifies the project/task. url optionally links to the result. idempotency_key prevents duplicate queue entries for an identical logical event.
Inputs: message (required), url, event, title, +2 more. Returns: deduplicated, notification
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 2 tools
The two tools are clearly distinct: notify creates/queues a notification, while notification_status reads its delivery state. There is no overlap in purpose or ambiguity about which to call.
The names are readable and individually clear, but they follow different conventions: 'notify' is a bare verb while 'notification_status' is a noun phrase without an action prefix. This is a minor inconsistency rather than chaotic naming.
Two tools is on the thin side for a notification server, but the pair covers the essential send-and-check workflow without unnecessary bloat. It feels slightly under-scoped but not unusably so.
The basic lifecycle of queueing and checking delivery status is covered, and the details around idempotency and state are thoughtfully described. Missing capabilities like canceling a queued notification or confirming read receipt are notable but not fatal gaps.
Build and send email, SMS, and push straight from your AI agent.
Let your AI agent notify you by email, Slack, Discord, or webhook. One tool: send_notification.
Email, WhatsApp and Telegram for AI agents: send, campaigns, automations, contacts, agent inboxes.
Send, search, and manage notifications, accounts, and push preferences
