Telegram Notifications MCP
Provides a send_notification tool for sending notifications through the Telegram Bot API to a preconfigured bot target, such as a private chat, group, channel, or forum topic. Each project is locked to one target and cannot read chats or choose a different recipient.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Telegram Notifications MCP
A simple secure MCP server for Telegram Bot API notifications.
What it does
Your AI agent gets one tool, send_notification. Each project is locked to one named target: a bot plus a chat, group, channel or forum topic. The agent cannot read your chats or pick a different recipient. Your personal account info is never used.
Local: each MCP client starts its own process on your machine.
Hosted: one HTTPS server serves many projects. Each project has its own key mapped to one target.
You need Node.js 20+ for local use, or Docker for hosted use.
Related MCP server: MCP-TG
Table of Contents
Before you start: create a bot
In Telegram, open @BotFather and send
/newbot.Follow the prompts. Save the HTTP API token somewhere private.
Note the bot's username (the
t.me/<username>part).
Only BotFather issues bot tokens. Never paste a token into an AI prompt, a repository, a browser URL, or an online "chat ID" service.
Then pick your setup:
The examples use the target name dev-status and the bot My_Alerts_Bot. Replace both with your own.
macOS (local)
1. Install and initialize
npm install --global telegram-notifications-mcp
telegram-notifs-mcp initThe npm package is telegram-notifications-mcp; the command it installs is telegram-notifs-mcp. init creates ~/.config/telegram-notifs-mcp/config.json with discovery on.
An existing config from before the rename is reused; open the path printed by init instead of the example below.
2. Add your target
open -e "$HOME/.config/telegram-notifs-mcp/config.json"Fill in targets, leaving everything else as is:
{
"targets": {
"dev-status": {
"bot": "My_Alerts_Bot",
"token": "123456789:your-botfather-token"
}
},
"clients": {},
"discovery": {
"enabled": true
}
}The file is private to your account. Don't add a chatId yet.
3. Say hello in Telegram
Do one of these in the destination you want notifications in:
Private chat: open
t.me/My_Alerts_Botand press Start.Group: add the bot and send
/start@My_Alerts_Bot. For a forum topic, send it inside that topic.Channel: add the bot as an admin that can post, then publish a post.
4. Discover the chat ID
Make sure nothing else is polling this bot (another script, a hosted copy of this server in discovery mode, etc.). Then use either option.
Command:
telegram-notifs-mcp discover --target dev-status --confirm-no-other-pollerAgent: add a temporary entry to your user-level MCP config (not the project's), then ask your agent to call discover_chats with {"source": "target", "name": "dev-status", "confirmNoOtherPoller": true}:
{
"servers": {
"telegram-discovery": {
"type": "stdio",
"command": "telegram-notifs-mcp",
"args": ["serve", "--discovery"]
}
}
}Either way, you get something like:
{
"chats": [
{
"chatId": -1001234567890,
"type": "supergroup",
"title": "Team alerts",
"threadIds": [42]
}
]
}5. Save the chat ID and test
Add chatId (keep the minus sign) and, for a forum topic only, threadId:
"dev-status": {
"bot": "My_Alerts_Bot",
"token": "123456789:your-botfather-token",
"chatId": -1001234567890,
"threadId": 42
}telegram-notifs-mcp check --target dev-status
telegram-notifs-mcp test-send dev-statuscheck sends nothing. test-send sends one real message; look for it in Telegram.
6. Turn off discovery
Set "enabled": false under discovery and remove the temporary telegram-discovery MCP entry if you added one.
7. Connect your project
In the project's .vscode/mcp.json:
{
"servers": {
"telegram-notifs-mcp": {
"type": "stdio",
"command": "telegram-notifs-mcp",
"args": ["serve", "--target", "dev-status"]
}
}
}Add "--label", "my-project" to the args to prefix messages with a project name. Other MCP clients use the same command and args in their own format. Every local project shares the same config.json; each is locked to the target in its own args.
Windows (local)
Run these in PowerShell.
1. Install and initialize
npm install --global telegram-notifications-mcp
telegram-notifs-mcp initThe npm package is telegram-notifications-mcp; the command it installs is telegram-notifs-mcp. init creates %LOCALAPPDATA%\telegram-notifs-mcp\config.json with discovery on. Access is restricted to your account automatically.
An existing config from before the rename is reused; open the path printed by init instead of the example below.
2. Add your target
notepad "$env:LOCALAPPDATA\telegram-notifs-mcp\config.json"Fill in targets, leaving everything else as is:
{
"targets": {
"dev-status": {
"bot": "My_Alerts_Bot",
"token": "123456789:your-botfather-token"
}
},
"clients": {},
"discovery": {
"enabled": true
}
}Don't add a chatId yet.
3. Say hello in Telegram
Do one of these in the destination you want notifications in:
Private chat: open
t.me/My_Alerts_Botand press Start.Group: add the bot and send
/start@My_Alerts_Bot. For a forum topic, send it inside that topic.Channel: add the bot as an admin that can post, then publish a post.
4. Discover the chat ID
Make sure nothing else is polling this bot. Then use either option.
Command:
telegram-notifs-mcp discover --target dev-status --confirm-no-other-pollerAgent: add a temporary entry to your user-level MCP config (not the project's), then ask your agent to call discover_chats with {"source": "target", "name": "dev-status", "confirmNoOtherPoller": true}:
{
"servers": {
"telegram-discovery": {
"type": "stdio",
"command": "telegram-notifs-mcp",
"args": ["serve", "--discovery"]
}
}
}Either way, look for the chatId (and threadIds for forum topics) in the chats list.
5. Save the chat ID and test
Add chatId (keep the minus sign) and, for a forum topic only, threadId:
"dev-status": {
"bot": "My_Alerts_Bot",
"token": "123456789:your-botfather-token",
"chatId": -1001234567890,
"threadId": 42
}telegram-notifs-mcp check --target dev-status
telegram-notifs-mcp test-send dev-statuscheck sends nothing. test-send sends one real message; look for it in Telegram.
6. Turn off discovery
Set "enabled": false under discovery and remove the temporary telegram-discovery MCP entry if you added one.
7. Connect your project
In the project's .vscode/mcp.json:
{
"servers": {
"telegram-notifs-mcp": {
"type": "stdio",
"command": "telegram-notifs-mcp",
"args": ["serve", "--target", "dev-status"]
}
}
}Add "--label", "my-project" to the args to prefix messages with a project name. Other MCP clients use the same command and args in their own format. If your client can't start telegram-notifs-mcp, see Troubleshooting.
Docker Compose (hosted)
Run these on your server. You also need an HTTPS reverse proxy in front of port 3000 (Caddy, nginx, Traefik, etc.); Compose only listens on 127.0.0.1:3000.
1. Configure and start
git clone https://github.com/gmoz22/telegram-notifications-mcp.git
cd telegram-notifications-mcp
cp .env.example .env
chmod 600 .envEdit .env:
TELEGRAM_DEV_BOT_TOKEN=123456789:your-botfather-token
TELEGRAM_MCP_ALLOWED_HOSTS=notify.example.comdocker compose up --build -dFirst start creates /data/config.json with discovery on, plus a private administrator key. To use other token variable names, add them to the environment list in docker-compose.yml.
2. Add your target
docker compose exec telegram-notifs-mcp vi /data/config.jsonAdd your target to targets. Keep the generated discovery block as is. The token is a reference to the .env variable:
"targets": {
"dev-status": {
"bot": "My_Alerts_Bot",
"token": "${TELEGRAM_DEV_BOT_TOKEN}"
}
}docker compose restart telegram-notifs-mcp3. Say hello in Telegram
Do one of these in the destination you want notifications in:
Private chat: open
t.me/My_Alerts_Botand press Start.Group: add the bot and send
/start@My_Alerts_Bot. For a forum topic, send it inside that topic.Channel: add the bot as an admin that can post, then publish a post.
4. Discover the chat ID
Make sure nothing else is polling this bot. Then use either option.
Command:
docker compose exec telegram-notifs-mcp node dist/cli.js discover \
--target dev-status --confirm-no-other-pollerAgent: get the administrator key from a trusted terminal:
docker compose exec telegram-notifs-mcp node dist/cli.js admin-key showAdd a temporary entry to your user-level VS Code MCP config. VS Code prompts for the key once and stores it securely:
{
"inputs": [
{
"type": "promptString",
"id": "telegram-admin-key",
"description": "Telegram MCP administrator key",
"password": true
}
],
"servers": {
"telegram-discovery": {
"type": "http",
"url": "https://notify.example.com/mcp",
"headers": {
"Authorization": "Bearer ${input:telegram-admin-key}"
}
}
}
}Ask your agent to call discover_chats with {"source": "target", "name": "dev-status", "confirmNoOtherPoller": true}. Never paste the key into the chat itself. This key can only discover; it cannot send.
Either way, look for the chatId (and threadIds for forum topics) in the chats list.
5. Save the chat ID and test
Edit /data/config.json again and add chatId (keep the minus sign) and, for a forum topic only, threadId:
"dev-status": {
"bot": "My_Alerts_Bot",
"token": "${TELEGRAM_DEV_BOT_TOKEN}",
"chatId": -1001234567890,
"threadId": 42
}docker compose restart telegram-notifs-mcp
docker compose exec telegram-notifs-mcp node dist/cli.js check --target dev-status
docker compose exec telegram-notifs-mcp node dist/cli.js test-send dev-status6. Create a project key
Do this before turning off discovery: hosted mode needs at least one project key once discovery is off.
docker compose exec telegram-notifs-mcp node dist/cli.js keygen \
--client my-project --target dev-statusThe key is printed once; copy it now. Only its hash is stored.
7. Turn off discovery
In /data/config.json, set "enabled": false under discovery. Then:
docker compose restart telegram-notifs-mcpRemove the temporary telegram-discovery MCP entry if you added one.
8. Connect your project
In the project's .vscode/mcp.json:
{
"inputs": [
{
"type": "promptString",
"id": "telegram-notif-key",
"description": "Telegram MCP project key",
"password": true
}
],
"servers": {
"telegram-notifs-mcp": {
"type": "http",
"url": "https://notify.example.com/mcp",
"headers": {
"Authorization": "Bearer ${input:telegram-notif-key}"
}
}
}
}Enter the project key from step 6 when prompted. Other MCP clients need the same URL and Authorization header, using their own secret mechanism.
Coolify (hosted)
1. Create the resource
In Coolify, create a new resource from the public repository
https://github.com/gmoz22/telegram-notifications-mcp.Choose the Docker Compose build pack and
docker-compose.yml.In Environment Variables, set:
TELEGRAM_DEV_BOT_TOKENto your BotFather token.TELEGRAM_MCP_ALLOWED_HOSTSto your domain, for examplenotify.example.com.
Assign your domain to the
telegram-notifs-mcpservice on port 3000, for examplehttps://notify.example.com:3000.Deploy.
Coolify generates TELEGRAM_MCP_ADMIN_KEY automatically and shows it in the Environment Variables tab. It stays the same across redeploys. To use other token variable names, add them to the environment list in docker-compose.yml.
2. Add your target
Open the service's Terminal in Coolify and run:
vi /data/config.jsonAdd your target to targets. Keep the generated discovery block as is. The token is a reference to the Coolify variable:
"targets": {
"dev-status": {
"bot": "My_Alerts_Bot",
"token": "${TELEGRAM_DEV_BOT_TOKEN}"
}
}Restart the service.
3. Say hello in Telegram
Do one of these in the destination you want notifications in:
Private chat: open
t.me/My_Alerts_Botand press Start.Group: add the bot and send
/start@My_Alerts_Bot. For a forum topic, send it inside that topic.Channel: add the bot as an admin that can post, then publish a post.
4. Discover the chat ID
Make sure nothing else is polling this bot. Then use either option.
Command: in the Coolify terminal:
node dist/cli.js discover --target dev-status --confirm-no-other-pollerAgent: copy TELEGRAM_MCP_ADMIN_KEY from Coolify's Environment Variables tab. Add a temporary entry to your user-level VS Code MCP config. VS Code prompts for the key once and stores it securely:
{
"inputs": [
{
"type": "promptString",
"id": "telegram-admin-key",
"description": "Telegram MCP administrator key",
"password": true
}
],
"servers": {
"telegram-discovery": {
"type": "http",
"url": "https://notify.example.com/mcp",
"headers": {
"Authorization": "Bearer ${input:telegram-admin-key}"
}
}
}
}Ask your agent to call discover_chats with {"source": "target", "name": "dev-status", "confirmNoOtherPoller": true}. Never paste the key into the chat itself. This key can only discover; it cannot send.
Either way, look for the chatId (and threadIds for forum topics) in the chats list.
5. Save the chat ID and test
Edit /data/config.json again and add chatId (keep the minus sign) and, for a forum topic only, threadId:
"dev-status": {
"bot": "My_Alerts_Bot",
"token": "${TELEGRAM_DEV_BOT_TOKEN}",
"chatId": -1001234567890,
"threadId": 42
}Restart the service, then in the terminal:
node dist/cli.js check --target dev-status
node dist/cli.js test-send dev-status6. Create a project key
Do this before turning off discovery: hosted mode needs at least one project key once discovery is off.
node dist/cli.js keygen --client my-project --target dev-statusThe key is printed once; copy it now. Only its hash is stored.
7. Turn off discovery
In /data/config.json, set "enabled": false under discovery, then restart the service. Remove the temporary telegram-discovery MCP entry if you added one.
8. Connect your project
In the project's .vscode/mcp.json:
{
"inputs": [
{
"type": "promptString",
"id": "telegram-notif-key",
"description": "Telegram MCP project key",
"password": true
}
],
"servers": {
"telegram-notifs-mcp": {
"type": "http",
"url": "https://notify.example.com/mcp",
"headers": {
"Authorization": "Bearer ${input:telegram-notif-key}"
}
}
}
}Enter the project key from step 6 when prompted. Other MCP clients need the same URL and Authorization header, using their own secret mechanism.
Reference
Config file shape and rules
A complete config with a local target and a hosted project:
{
"targets": {
"dev-status": {
"bot": "My_Alerts_Bot",
"token": "123456789:your-botfather-token",
"chatId": 123456789
},
"ops-alerts": {
"bot": "My_Ops_Bot",
"token": "${TELEGRAM_OPS_BOT_TOKEN}",
"chatId": -1001234567890,
"threadId": 42
}
},
"clients": {
"my-project": {
"target": "ops-alerts",
"keySha256": "written-by-keygen"
}
},
"discovery": {
"enabled": false
}
}Field | Rules |
Target and client names | Lowercase letters, digits, and single hyphens, such as |
| The bot's username, 5-32 letters, digits, or |
| A literal BotFather token, or exactly |
| A non-zero integer. Groups and channels are negative; keep the minus sign. |
| Optional positive integer, only for forum topics. |
| Hosted only. Written by |
|
|
| Hosted only. Written automatically; it is a hash, not a usable key. |
Other rules:
Targets accept only
bot,token,chatId, andthreadId.A target without
chatIdis allowed only while discovery is on. It can be discovered but cannot send. Never use0or a placeholder.Every
${VAR_NAME}token must resolve, even after setup.A literal token makes the file a credential. Never commit it or copy it into a project.
Config file locations and overrides
Platform | Default path |
macOS / Linux |
|
Windows |
|
Docker / Coolify |
|
The first match wins:
TELEGRAM_NOTIF_CONFIG: the whole JSON document as an environment variable (read-only;initandkeygenwon't work).--config /path/to/file.jsonon any command.TELEGRAM_NOTIF_CONFIG_FILE: a file path.The default path above, or an existing legacy file.
Environment variables
Variable | Purpose |
| Inline JSON config; overrides any file. |
| Config file path ( |
|
|
| Hosted admin key (32-256 of |
| Comma-separated hostnames accepted over HTTP, such as |
| Optional browser origins to allow. |
| HTTP bind address ( |
| HTTP port, default |
| Any name you reference as |
Commands
In Docker, prefix commands with docker compose exec telegram-notifs-mcp node dist/cli.js. In the Coolify terminal, use node dist/cli.js.
Command | What it does |
| Creates the config with discovery on. Safe to rerun. |
| Also creates the managed admin key (done automatically in Docker). |
| Lists recent chats and topics for the target's bot. |
| Verifies bot and chat with Telegram; sends nothing. |
| Sends one real test message. |
| Starts the local MCP server for one target. |
| Starts a local admin-only discovery MCP server. |
| Starts the hosted HTTP server (Docker default). |
| Creates a hosted project key; add |
| Creates or replaces the managed admin key. |
| Prints the managed admin key. |
All commands accept --config <file>.
MCP tools
send_notification is the only tool for project clients:
Argument | Details |
| Required, 1-4096 characters. Text that looks like a bot token is rejected. |
|
|
| Optional; |
Hosted messages are prefixed with the client name. Local messages are prefixed only with --label. Failed sends are not retried, and success is reported only after Telegram confirms delivery.
discover_chats is the only tool for admin clients, and only while discovery is on:
Argument | Details |
|
|
| The target name. |
| Must be |
It returns chat IDs, types, titles, and forum topic IDs, never message text, tokens, or webhook URLs. Treat titles as untrusted text.
Telegram limits
Discovery uses Telegram's getUpdates:
It is not a list of every chat. Telegram keeps updates for only 24 hours, so say hello in the destination shortly before you discover.
It reads at most 100 pending updates.
mayHaveMore: truemeans older updates may be hiding newer chats.It doesn't mark updates as read, so repeated calls can return the same results.
It cannot run while the bot has a webhook. Discovery refuses rather than removing it.
It cannot detect another process polling the same bot. Running both can cause conflicts, which is why you must confirm no other poller.
For sending:
Messages are limited to 4096 characters.
Telegram allows roughly one message per second per chat, about 20 per minute in a group, and about 30 per second per bot.
The hosted server also limits each target to one send per second and each project to 30 sends per minute. Limits are per process; replicas don't share them.
Local processes have no shared limiter; Telegram's limits still apply.
Applying changes
Setup | After editing | After changing environment variables |
macOS / Windows commands | Nothing; each command rereads the file. | Rerun in a shell with the new value. |
macOS / Windows MCP | Restart the server from your MCP client. | Restart the MCP client's server. |
Docker Compose |
|
|
Coolify | Restart the service. | Redeploy. |
keygen changes also need a restart in hosted mode.
Updating and pinning versions
Local installs come from npm:
npm install --global telegram-notifications-mcp@latest # update
npm install --global telegram-notifications-mcp@1 # stay on 1.xTo pin an exact release, append its version, for example @1.0.2 if that release is available. Restart your MCP servers after updating and change their configured command. Your config.json is not touched.
To skip the global install, an MCP entry can run the package through npx instead:
{
"type": "stdio",
"command": "npx",
"args": [
"--yes",
"telegram-notifications-mcp@1",
"serve",
"--target",
"dev-status"
]
}Run npx --yes telegram-notifications-mcp@1 init once to create the config. The first start downloads the package, so it is slower.
Docker and Coolify build from this repository, so redeploy to update. You can pin a Git tag once a corresponding release tag exists.
When upgrading an existing Compose deployment, preserve the original Compose project name and its telegram-notif-data volume. The service is now named telegram-notifs-mcp; remove the old service container during the upgrade, for example with docker compose up --build -d --remove-orphans using the same project name. That option also removes any other orphan containers in the project, so inspect them first. If the checkout directory changed, use -p <old-project> or COMPOSE_PROJECT_NAME to select the original project. Do not remove the volume. In Coolify, confirm the renamed service retains the existing /data volume and update its domain routing before deploying.
Adding another destination later
Turn discovery back on (
"enabled": true, or setTELEGRAM_MCP_DISCOVERY_ENABLED=true) and restart if hosted.Add the new target without a
chatId.Repeat steps 3-5 of your setup.
Hosted: create a project key for it with
keygen.Turn discovery off again.
Security notes
Keep
config.jsonprivate and out of repositories.initrestricts its permissions automatically.Never put bot tokens or keys in prompts, project files, or logs.
The admin key can only discover chats. A project key can only send to its one target. Never give a project the admin key.
Only key hashes are stored for project keys; a lost key must be rotated.
Anyone who can see Coolify's environment variables can read
TELEGRAM_MCP_ADMIN_KEY.In plain Docker, the managed admin key lives in
/data/config.json.secrets/admin.key. Back up all of/data.Always serve hosted mode over HTTPS.
Keep discovery off except during setup.
Troubleshooting
Message or symptom | Fix |
| Run discovery and add the |
| Add the |
| Set it for the process running the server or command. |
| Fix the |
| Turn discovery on and restart if hosted. |
| Get IDs from the webhook's own logs, or use a different bot. |
| Another process is polling the bot. Stop it and retry. |
Discovery returns no chats | Say hello in the destination again (updates expire after 24 hours), then retry. |
| Run |
HTTP | Wrong or missing key, or a new key used before restarting. |
Hosted requests rejected by host | Add your domain to |
|
|
Windows MCP client can't start | Use |
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
WhatsApp and Telegram for AI agents, behind a policy gateway. OAuth or access key.
Let AI assistants post to your Telegram chats, groups and channels. Not affiliated with Telegram.
Run a Telegram channel from your AI agent. Posts go out through your own bot, not your account.
Send AI results to Telegram as private notifications or channel posts. No copy-pasting - connect your Telegram account and publish directly from AI assistants.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to send and receive messages, media, and files on Telegram, and manage chats via a bot token.1755 PyPIMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to interact with Telegram through 50+ tools for chats, messages, contacts, users, groups, and channels, with per-topic isolation and a reactive inbox for multi-agent use.MIT
- AlicenseNot gradedqualityCmaintenanceEnables an LLM to send text messages, documents, photos, videos, and audio to a fixed Telegram recipient via a Telegram bot, with no incoming-message tools or polling.1MIT
- AlicenseNot gradedqualityFmaintenanceEnables agents to relay private Telegram messages with registered humans and other agents through a self-hosted, single-owner deployment. It supports bound Telegram bots, inbox acknowledgment flows, and optional routes for ChatGPT dot and xAI Grokbot.1MIT