Watch Tower MCP server
Commit Oct 30, 2026Lets AI agents and applications fan out notifications to multiple channels like Telegram, Pushover, and ntfy via MCP or REST API.
Also known as MMTE/watch-tower
- Stars
- 0
- Tools
- 4
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 30, 2026
- License
- MIT
What is Watch Tower MCP?
Watch Tower lets AI agents and applications fan out notifications to multiple channels like Telegram, Pushover, and ntfy via MCP or REST API. It exposes 4 tools, such as send, send_file, get_replies.
Summary generated from the project's README
About Watch Tower MCP server
Developers and AI agents can distribute notifications across multiple communication platforms through a single interface. This system acts as a pluggable hub that fans out messages to channels including Telegram, Bale, Pushover, Gotify, and ntfy. It is designed for both local use via stdio and remote use through a REST API, making it suitable for integrating into automated workflows or standalone applications.
Users interact with the service using specific tools like send, send_file, get_replies, and list_channels. The setup requires Node.js and configuration of environment variables for the chosen notification providers, such as TELEGRAM_BOT_TOKEN or NTFY_TOPIC. For AI agents, the server provides a way to not only push alerts but also read human responses via a two-way communication loop, allowing for threaded conversations using message IDs.
What you can do with it
- 1Distribute multi-channel alertsAn AI agent can send a single notification that simultaneously reaches Telegram, ntfy, and Pushover.
- 2Handle human feedback loopsAn agent can send a message and then wait for a human to reply via a Telegram chat to continue the task.
- 3Ingest Slack-formatted webhooksExternal monitoring systems can send alerts to this hub by using the Slack webhook format.
Written from the project's README. Every use case is checked against a quote from it.
Watch Tower MCP tools 4
Detected from the READMEsendsend_fileget_replieslist_channels
Configuration
NTFY_TOPICTELEGRAM_BOT_TOKENTELEGRAM_CHAT_IDWATCHTOWER_MCP
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablemmte/watch-tower is public and reachablegithub.com/mmte/watch-tower ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-30github.com/mmte/watch-tower ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model4 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubWatch Tower
Pluggable notification hub for AI agents and apps. One MCP server + one REST API that fan out to multiple notification channels.
Built-in channels: Telegram · Bale · Pushover · Gotify · ntfy.
No web UI — interact via the Telegram bot, the REST API, or the MCP server. Adding a new channel takes ~50 lines of code.
╭──────────────╮ ╭──────────────╮ ╭─────────────╮
│ AI agent │ │ Your app │ │ Telegram │
│ (MCP tool) │ │ (REST) │ │ bot user │
╰──────┬───────╯ ╰──────┬───────╯ ╰──────┬──────╯
│ │ │
▼ ▼ ▼
╰──────▶ ╭──────────────────────────╮ ◀──╯
│ Watch Tower │
│ dispatcher (fan-out) │
╰────┬────┬────┬────┬──────╯
▼ ▼ ▼ ▼ ▼
Telegram Bale Push Gotify ntfy
Quick start
git clone https://github.com/MMTE/watch-tower.git
cd watch-tower
cp .env.example .env # fill in only the channels you want
npm install
npm start # REST API + Telegram bot
npm run mcp # MCP server over stdio (for AI agents)
npm test # smoke test, no network required
Requires Node ≥ 20 (uses global fetch / FormData).
With Docker:
cp .env.example .env
docker compose up -d --build
Deploy on Railway
Uses the existing Dockerfile and railway.json (healthcheck on /api/health, restart on failure). After the first deploy:
- Set
API_KEYand any channel credentials (TELEGRAM_BOT_TOKEN,NTFY_TOPIC, …) in the Variables tab. - Under Settings → Networking, generate a public domain.
- Set
WEBHOOK_URLto that public HTTPS URL (no trailing slash) — Telegram then uses webhook mode instead of polling. - Redeploy.
Railway injects PORT; the app picks it up automatically.
Heads up on the free / Hobby tier: Railway sleeps idle apps, which means alerts sent while the service is asleep are lost (Telegram drops webhook updates after retries; the others have no retry at all). For production alerting, use the paid plan or a host that doesn't idle.
Channels
A channel is enabled when its environment variables are set. Disabled channels are silently skipped.
| Channel | text | files | two-way | Required env | Notes |
|---|---|---|---|---|---|
telegram |
✅ | ✅ | ✅ capture + threading | TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID |
Bot UI + native file uploads |
bale |
✅ | ✅ | ❌ (roadmap) | BALE_BOT_TOKEN, BALE_CHAT_ID |
Telegram-compatible BotAPI |
pushover |
✅ | text fallback | ❌ (provider limit) | PUSHOVER_APP_TOKEN, PUSHOVER_USER_KEY |
Priority maps from level |
gotify |
✅ | text fallback | ❌ (provider limit) | GOTIFY_URL, GOTIFY_APP_TOKEN |
Files sent as inline text |
ntfy |
✅ | ✅ | ❌ (roadmap: action buttons) | NTFY_TOPIC (+ NTFY_URL, auth) |
Native Title/Priority/Tags |
Set DEFAULT_CHANNELS=telegram,ntfy to scope the default fan-out list. Every API/MCP request can also override with its own channels field.
Channel roadmap
- Bale two-way reply capture (mirrors the Telegram inbox).
- ntfy action buttons (approve/deny callbacks landing in the same inbox).
- Reply webhooks: push each captured reply to an agent runtime instead of polling.
- Support multiple configured instances of the same channel type, while keeping current single-instance env vars backward compatible. Example selectors:
telegram:ops,telegram:dev,ntfy:prod,ntfy:dev.
Severity → priority mapping
| Level | Pushover | Gotify | ntfy |
|---|---|---|---|
info |
-1 | 2 | 2 |
warn |
0 | 5 | 3 |
REST API
Base path: /api. All endpoints except /health require an x-api-key header, ?key=, or Authorization: Bearer token.
POST /api/send
The canonical endpoint. alert / log / agent below are sugar over it.
curl -X POST $BASE/api/send -H "Content-Type: application/json" -H "x-api-key: $KEY" \
-d '{"text":"deploy done","title":"prod","level":"info","channels":["telegram","ntfy"],"reply_to":4578}'
| Field | Type | Notes |
|---|---|---|
text |
string | Required. Message body |
title? |
string | Bold header on chat channels |
level? |
enum | info | warn | error | critical |
channels? |
array | Channel names; omit for defaults / all enabled |
reply_to? |
number | Telegram message_id to thread into |
POST /api/alert, POST /api/log, POST /api/agent
Sugar over /api/send: alert = {level, title, message}, log = {source, log}
(code-formatted), agent = {repo, summary, kind, issue?, issue_url?} (checkpoint
format). All accept channels and compile into the same dispatch.
POST /api/hooks/slack
Webhook ingest for external systems that speak the Slack webhook format
({text, attachments[]}). Built for GlitchTip's "webhook" alert recipient
(point it at $BASE/api/hooks/slack?key=$KEY) and works with any
Slack-compatible producer. The first attachment becomes the message title
(level emoji derived from its color), attachment text, fields and
title_link become the body.
POST /api/file
curl -X POST $BASE/api/file -H "x-api-key: $KEY" \
-F "file=@report.pdf" -F "filename=daily-report.pdf" -F "caption=Daily report" \
-F "reply_to=4578" -F "channels=telegram,pushover"
Response shape
{ "ok": true, "delivered": ["telegram"], "errors": [], "message_ids": { "telegram": 4578 } }
ok is true if at least one channel delivered (else HTTP 502). message_ids carries
the provider message id per channel when available (Telegram today) — use it as reply_to
to thread. An unknown channel name returns 400 with the available list in the message.
Reading replies (two-way)
Messages the authorized Telegram chat sends to the bot are captured with their
reply_to_message_id and polled by agents:
# everything after high-water mark 4578, long-poll up to 30s for the next one
curl "$BASE/api/agent/replies?since=4578&wait=30" -H "x-api-key: $KEY"
| Param | Notes |
|---|---|
since |
only entries with id > since (default 0 = all) |
limit |
most recent N, oldest first |
wait |
long-poll seconds, capped at 55 |
Each entry: { id, text, chat_id, reply_to_message_id, reference, ts }. The bot reacts 👍
to every captured message so the human knows it landed; the answer comes from your agent.
MCP server (for AI agents)
Stdio transport. For the HTTP transport (POST /mcp with an API key), deploy the server and point MCP clients at its URL. Configure a stdio client with node /path/to/src/mcp.js:
{
"mcpServers": {
"watch-tower": {
"command": "node",
"args": ["/absolute/path/to/watch-tower/src/mcp.js"],
"env": {
"TELEGRAM_BOT_TOKEN": "...",
"TELEGRAM_CHAT_ID": "...",
"NTFY_TOPIC": "...",
"WATCHTOWER_MCP": "1"
}
}
}
}
Tools
| Tool | Params | Description |
|---|---|---|
send |
text, title?, level?, channels?, reply_to? |
Notify a human; result carries message_id |
send_file |
path, caption?, filename?, reply_to?, … |
Send a local file |
get_replies |
since?, wait? (0–60s), limit? |
Read human replies, optional long-poll |
list_channels |
— | Configured state + two-way capability |
The server's instructions teach the loop: send → note the message_id →
get_replies({ since, wait }) → the answer arrives with reply_to_message_id →
send(..., { reply_to }) threads the follow-up. level maps to native priority on
Pushover/Gotify/ntfy; channels selects specific channels, omitted = defaults.
Web pages
/status— public liveness page: confirms the service is up, nothing more. Channel states, inbox, version and environment are not exposed publicly./admin?key=…— API-key-gated admin page: recent sends, inbox, channel states, and a test-send form for one-click channel debugging.
Telegram bot commands
| /start | Register and get chat ID |
| /ping | Liveness check |
| /id | Show your chat ID |
| /status | Uptime, memory, active channels |
| /channels | List configured channels |
| /help | Show help |
| /time | Server time |
| /echo <text> | Echo back |
Project layout
src/
├── index.js Entry: REST + bot + status page
├── app.js Express factory, /status, /admin, /mcp (HTTP)
├── api.js REST routes
├── agent.js Agent notify + replies inbox endpoint
├── auth.js Shared API-key middleware
├── replies.js Reply inbox store (capture / list / waitFor)
├── bot.js Telegram bot UI (commands)
├── mcp.js MCP stdio entry
├── mcpServer.js MCP tools (send, send_file, get_replies, list_channels)
└── channels/
├── index.js Registry + dispatcher (notify / notifyFile)
├── telegram.js
├── bale.js
├── pushover.js
├── gotify.js
└── ntfy.js
test/
└── smoke.js No-network unit + HTTP smoke
Adding a channel
See CONTRIBUTING.md. TL;DR: drop a module in src/channels/ exporting { name, enabled, sendMessage, sendFile } and register it in src/channels/index.js.
Contributing & security
- Contributions: see CONTRIBUTING.md.
- Vulnerability reports: see SECURITY.md. Please don't open a public issue for security problems.
- Changes by release: see CHANGELOG.md.
License
MIT — see LICENSE.
Watch Tower MCP questions
What tools does Watch Tower MCP provide?
It exposes 4 tools, including send, send_file, get_replies, list_channels.
What notification channels are supported?
The server includes built-in support for Telegram, Bale, Pushover, Gotify, and ntfy.
How can I interact with Watch Tower?
You can interact with the service via the Telegram bot, the REST API, or the MCP server.
Can AI agents read replies from humans?
Yes, the MCP server provides a tool to read human replies captured from Telegram, allowing for two-way communication.