Sends outbound notifications to Telegram via a bot, supporting message types like question, plan_ready, final, attention_needed, and error.
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., "@telegram-mcp-notify Notify me that the plan is ready"
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.
Notify-only Telegram MCP server for AI coding agents (Cursor, Codex, Claude Code).
This repository is still in active development and currently intended for personal/self use and experimentation. APIs and behavior may change without notice. Use at your own risk.
Related MCP server: telegram-mcp
Removed console script: telegram-mcp-listener
Removed reply/input internals (inbox, listener lifecycle, pending prompts)
Removed singleton lock behavior for server startup
Outbound Telegram notifications for:
question
plan_ready
final
attention_needed
error
Notify-only MCP surface:
send_telegram_notification
telegram_notify_capabilities
Cross-platform runtime (Windows and POSIX)
Python 3.11+
uv / uvx (recommended) or pip
Telegram bot token (from @BotFather)
Telegram chat ID
Create .cursor/mcp.json in your project root (or ~/.cursor/mcp.json globally):
{
"mcpServers": {
"telegram_notify": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/hyper-tew/telegram-mcp-notify",
"telegram-mcp-notify"
],
"env": {
"TELEGRAM_BOT_TOKEN": "123456:ABC-DEF...",
"TELEGRAM_CHAT_ID": "123456789"
}
}
}
}Restart Cursor after saving.
Add to ~/.codex/config.toml:
[mcp_servers.telegram_notify]
command = "uvx"
args = ["--from", "git+https://github.com/hyper-tew/telegram-mcp-notify", "telegram-mcp-notify"]
[mcp_servers.telegram_notify.env]
TELEGRAM_BOT_TOKEN = "123456:ABC-DEF..."
TELEGRAM_CHAT_ID = "123456789"Or via CLI:
codex mcp add telegram_notify \
--env TELEGRAM_BOT_TOKEN=123456:ABC-DEF... \
--env TELEGRAM_CHAT_ID=123456789 \
-- uvx --from "git+https://github.com/hyper-tew/telegram-mcp-notify" telegram-mcp-notify# From GitHub
pip install git+https://github.com/hyper-tew/telegram-mcp-notify.git
# From local clone
pip install ./telegram-mcp-notify
# Development
pip install -e "./telegram-mcp-notify[dev]"Then use Python module mode in MCP config:
[mcp_servers.telegram_notify]
command = "python"
args = ["-m", "telegram_mcp_notify.server"]
[mcp_servers.telegram_notify.env]
TELEGRAM_BOT_TOKEN = "123456:ABC-DEF..."
TELEGRAM_CHAT_ID = "123456789"Required:
TELEGRAM_BOT_TOKEN
TELEGRAM_CHAT_ID
Optional:
Variable | Default | Description |
| None | Message parse mode ( |
|
| Suppress outbound notifications |
|
| HTTP request timeout |
Tool | Description |
| Send a structured Telegram checkpoint notification |
| Return current server tool/capability surface |
Symptom | Cause | Fix |
No notifications received | Invalid token/chat ID | Verify |
Unexpected tools shown | Running old package version | Upgrade/restart MCP runtime |
| Executable not on PATH | Use |
|
| Install |
MIT
This server cannot be deployed
Let your AI agent notify you by email, Slack, Discord, or webhook. One tool: send_notification.
Run a Telegram channel from your AI agent. Posts go out through your own bot, not your account.
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Push notifications for AI agents - send instant iPhone notifications from any MCP client.
