Telegram Notifications MCP
by gmoz22
README.md
# Telegram Notifications MCP
   [](https://www.npmjs.com/package/telegram-notifications-mcp) 
A simple secure MCP server for Telegram Bot API notifications.
<br/>
## 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.
<br/>
## Table of Contents
- [Before you start: create a bot](#before-you-start-create-a-bot)
- [macOS (local)](#macos-local)
- [Windows (local)](#windows-local)
- [Docker Compose (hosted)](#docker-compose-hosted)
- [Coolify (hosted)](#coolify-hosted)
- [Reference](#reference)
<br/>
## Before you start: create a bot
1. In Telegram, open [@BotFather](https://t.me/BotFather) and send `/newbot`.
2. Follow the prompts. Save the **HTTP API token** somewhere private.
3. 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:
- [macOS (local)](#macos-local)
- [Windows (local)](#windows-local)
- [Docker Compose (hosted)](#docker-compose-hosted)
- [Coolify (hosted)](#coolify-hosted)
The examples use the target name `dev-status` and the bot `My_Alerts_Bot`. Replace both with your own.
<br/>
## macOS (local)
### 1. Install and initialize
```sh
npm install --global telegram-notifications-mcp
telegram-notifs-mcp init
```
The 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
```sh
open -e "$HOME/.config/telegram-notifs-mcp/config.json"
```
Fill in `targets`, leaving everything else as is:
```json
{
"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_Bot` and 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:**
```sh
telegram-notifs-mcp discover --target dev-status --confirm-no-other-poller
```
**Agent:** 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}`:
```json
{
"servers": {
"telegram-discovery": {
"type": "stdio",
"command": "telegram-notifs-mcp",
"args": ["serve", "--discovery"]
}
}
}
```
Either way, you get something like:
```json
{
"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`:
```json
"dev-status": {
"bot": "My_Alerts_Bot",
"token": "123456789:your-botfather-token",
"chatId": -1001234567890,
"threadId": 42
}
```
```sh
telegram-notifs-mcp check --target dev-status
telegram-notifs-mcp test-send dev-status
```
`check` 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`:
```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.
<br/>
## Windows (local)
Run these in PowerShell.
### 1. Install and initialize
```powershell
npm install --global telegram-notifications-mcp
telegram-notifs-mcp init
```
The 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
```powershell
notepad "$env:LOCALAPPDATA\telegram-notifs-mcp\config.json"
```
Fill in `targets`, leaving everything else as is:
```json
{
"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_Bot` and 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:**
```powershell
telegram-notifs-mcp discover --target dev-status --confirm-no-other-poller
```
**Agent:** 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}`:
```json
{
"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`:
```json
"dev-status": {
"bot": "My_Alerts_Bot",
"token": "123456789:your-botfather-token",
"chatId": -1001234567890,
"threadId": 42
}
```
```powershell
telegram-notifs-mcp check --target dev-status
telegram-notifs-mcp test-send dev-status
```
`check` 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`:
```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](#troubleshooting).
<br/>
## 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
```sh
git clone https://github.com/gmoz22/telegram-notifications-mcp.git
cd telegram-notifications-mcp
cp .env.example .env
chmod 600 .env
```
Edit `.env`:
```sh
TELEGRAM_DEV_BOT_TOKEN=123456789:your-botfather-token
TELEGRAM_MCP_ALLOWED_HOSTS=notify.example.com
```
```sh
docker compose up --build -d
```
First 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
```sh
docker compose exec telegram-notifs-mcp vi /data/config.json
```
Add your target to `targets`. Keep the generated `discovery` block as is. The token is a reference to the `.env` variable:
```json
"targets": {
"dev-status": {
"bot": "My_Alerts_Bot",
"token": "${TELEGRAM_DEV_BOT_TOKEN}"
}
}
```
```sh
docker compose restart telegram-notifs-mcp
```
### 3. Say hello in Telegram
Do one of these in the destination you want notifications in:
- **Private chat:** open `t.me/My_Alerts_Bot` and 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:**
```sh
docker compose exec telegram-notifs-mcp node dist/cli.js discover \
--target dev-status --confirm-no-other-poller
```
**Agent:** get the administrator key from a trusted terminal:
```sh
docker compose exec telegram-notifs-mcp node dist/cli.js admin-key show
```
Add a temporary entry to your _user-level_ VS Code MCP config. VS Code prompts for the key once and stores it securely:
```json
{
"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`:
```json
"dev-status": {
"bot": "My_Alerts_Bot",
"token": "${TELEGRAM_DEV_BOT_TOKEN}",
"chatId": -1001234567890,
"threadId": 42
}
```
```sh
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-status
```
### 6. Create a project key
Do this **before** turning off discovery: hosted mode needs at least one project key once discovery is off.
```sh
docker compose exec telegram-notifs-mcp node dist/cli.js keygen \
--client my-project --target dev-status
```
The 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:
```sh
docker compose restart telegram-notifs-mcp
```
Remove the temporary `telegram-discovery` MCP entry if you added one.
### 8. Connect your project
In the project's `.vscode/mcp.json`:
```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.
<br/>
## Coolify (hosted)
### 1. Create the resource
1. In Coolify, create a new resource from the public repository `https://github.com/gmoz22/telegram-notifications-mcp`.
2. Choose the **Docker Compose** build pack and `docker-compose.yml`.
3. In **Environment Variables**, set:
- `TELEGRAM_DEV_BOT_TOKEN` to your BotFather token.
- `TELEGRAM_MCP_ALLOWED_HOSTS` to your domain, for example `notify.example.com`.
4. Assign your domain to the `telegram-notifs-mcp` service on port 3000, for example `https://notify.example.com:3000`.
5. 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:
```sh
vi /data/config.json
```
Add your target to `targets`. Keep the generated `discovery` block as is. The token is a reference to the Coolify variable:
```json
"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_Bot` and 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:
```sh
node dist/cli.js discover --target dev-status --confirm-no-other-poller
```
**Agent:** 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:
```json
{
"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`:
```json
"dev-status": {
"bot": "My_Alerts_Bot",
"token": "${TELEGRAM_DEV_BOT_TOKEN}",
"chatId": -1001234567890,
"threadId": 42
}
```
Restart the service, then in the terminal:
```sh
node dist/cli.js check --target dev-status
node dist/cli.js test-send dev-status
```
### 6. Create a project key
Do this **before** turning off discovery: hosted mode needs at least one project key once discovery is off.
```sh
node dist/cli.js keygen --client my-project --target dev-status
```
The 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`:
```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.
<br/>
## Reference
- [Config file shape and rules](#config-file-shape-and-rules)
- [Config file locations and overrides](#config-file-locations-and-overrides)
- [Environment variables](#environment-variables)
- [Commands](#commands)
- [MCP tools](#mcp-tools)
- [Telegram limits](#mcp-tools)
- [Applying changes](#applying-changes)
- [Adding another destination later](#adding-another-destination-later)
- [Security notes](#security-notes)
- [Troubleshooting](#troubleshooting)
### Config file shape and rules
A complete config with a local target and a hosted project:
```json
{
"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 `dev-status`. |
| `bot` | The bot's username, 5-32 letters, digits, or `_`. `check` verifies it matches the token. |
| `token` | A literal BotFather token, or exactly `${VAR_NAME}` (uppercase) to read an environment variable. |
| `chatId` | A non-zero integer. Groups and channels are negative; keep the minus sign. |
| `threadId` | Optional positive integer, only for forum topics. |
| `clients` | Hosted only. Written by `keygen`; maps a project to one target with a key hash. |
| `discovery.enabled` | `true` during setup, `false` afterward. |
| `discovery.adminKeySha256` | Hosted only. Written automatically; it is a hash, not a usable key. |
Other rules:
- Targets accept only `bot`, `token`, `chatId`, and `threadId`.
- A target without `chatId` is allowed only while discovery is on. It can be discovered but cannot send. Never use `0` or 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 | `~/.config/telegram-notifs-mcp/config.json` |
| Windows | `%LOCALAPPDATA%\telegram-notifs-mcp\config.json` |
| Docker / Coolify | `/data/config.json` (persistent volume) |
The first match wins:
1. `TELEGRAM_NOTIF_CONFIG`: the whole JSON document as an environment variable (read-only; `init` and `keygen` won't work).
2. `--config /path/to/file.json` on any command.
3. `TELEGRAM_NOTIF_CONFIG_FILE`: a file path.
4. The default path above, or an existing legacy file.
### Environment variables
| Variable | Purpose |
| --- | --- |
| `TELEGRAM_NOTIF_CONFIG` | Inline JSON config; overrides any file. |
| `TELEGRAM_NOTIF_CONFIG_FILE` | Config file path (`/data/config.json` in Docker). |
| `TELEGRAM_MCP_DISCOVERY_ENABLED` | `true` or `false`; overrides `discovery.enabled` when set. |
| `TELEGRAM_MCP_ADMIN_KEY` | Hosted admin key (32-256 of `A-Z a-z 0-9 - _`); replaces the managed key. Coolify sets it. |
| `TELEGRAM_MCP_ALLOWED_HOSTS` | Comma-separated hostnames accepted over HTTP, such as `notify.example.com`. |
| `TELEGRAM_MCP_ALLOWED_ORIGINS` | Optional browser origins to allow. |
| `TELEGRAM_MCP_HOST` | HTTP bind address (`127.0.0.1`; `0.0.0.0` in Docker). |
| `TELEGRAM_MCP_PORT` | HTTP port, default `3000`. |
| `TELEGRAM_*_BOT_TOKEN` | Any name you reference as `${VAR_NAME}` in a target's `token`. |
### 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 |
| --- | --- |
| `init` | Creates the config with discovery on. Safe to rerun. |
| `init --hosted` | Also creates the managed admin key (done automatically in Docker). |
| `discover --target <name> --confirm-no-other-poller` | Lists recent chats and topics for the target's bot. |
| `check [--target <name>]` | Verifies bot and chat with Telegram; sends nothing. |
| `test-send <target>` | Sends one real test message. |
| `serve --target <name> [--label <text>]` | Starts the local MCP server for one target. |
| `serve --discovery` | Starts a local admin-only discovery MCP server. |
| `serve --http [--initialize]` | Starts the hosted HTTP server (Docker default). |
| `keygen --client <name> --target <name>` | Creates a hosted project key; add `--rotate` to replace it. |
| `keygen --admin [--rotate]` | Creates or replaces the managed admin key. |
| `admin-key show` | Prints the managed admin key. |
All commands accept `--config <file>`.
### MCP tools
`send_notification` is the only tool for project clients:
| Argument | Details |
| --- | --- |
| `text` | Required, 1-4096 characters. Text that looks like a bot token is rejected. |
| `format` | `plain` (default) or `html` ([Telegram's HTML subset](https://core.telegram.org/bots/api#html-style)). |
| `silent` | Optional; `true` delivers without a notification sound. |
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 |
| ---------------------- | ------------------------------- |
| `source` | `target` to use a target's bot. |
| `name` | The target name. |
| `confirmNoOtherPoller` | Must be `true`. |
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`](https://core.telegram.org/bots/api#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: true` means 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 `config.json` | 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 | `docker compose restart telegram-notifs-mcp` | `docker compose up -d --force-recreate` |
| Coolify | Restart the service. | Redeploy. |
`keygen` changes also need a restart in hosted mode.
### Updating and pinning versions
Local installs come from [npm](https://www.npmjs.com/package/telegram-notifications-mcp):
```sh
npm install --global telegram-notifications-mcp@latest # update
npm install --global telegram-notifications-mcp@1 # stay on 1.x
```
To 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:
```json
{
"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
1. Turn discovery back on (`"enabled": true`, or set `TELEGRAM_MCP_DISCOVERY_ENABLED=true`) and restart if hosted.
2. Add the new target without a `chatId`.
3. Repeat steps 3-5 of your setup.
4. Hosted: create a project key for it with `keygen`.
5. Turn discovery off again.
### Security notes
- Keep `config.json` private and out of repositories. `init` restricts 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 |
| --- | --- |
| `Target "x" has no chatId. Complete discovery before sending.` | Run discovery and add the `chatId`. |
| `Target "x" requires a chatId when discovery is disabled.` | Add the `chatId`, remove the target, or turn discovery back on. |
| `Environment variable X for ... is not set.` | Set it for the process running the server or command. |
| `... token does not match the configured bot username.` | Fix the `bot` username or the token. |
| `Discovery is disabled.` | Turn discovery on and restart if hosted. |
| `This bot has a webhook; getUpdates cannot be used.` | Get IDs from the webhook's own logs, or use a different bot. |
| `Telegram rejected getUpdates (HTTP 409) ...` | 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. |
| `Hosted mode requires a client, or enabled discovery ...` | Run `keygen` before turning off discovery. |
| HTTP `401 Unauthorized` | Wrong or missing key, or a new key used before restarting. |
| Hosted requests rejected by host | Add your domain to `TELEGRAM_MCP_ALLOWED_HOSTS`. |
| `admin-key show` refuses to run | `TELEGRAM_MCP_ADMIN_KEY` is set; read it from your platform instead. |
| Windows MCP client can't start `telegram-notifs-mcp` | Use `node` as the command and `<npm root -g>\telegram-notifications-mcp\dist\cli.js` as the first argument. |
This server cannot be deployed
Maintenance
ActivityNo data
ResponsivenessOutdated data