telegram-notifier-mcp
Allows sending text messages and files (documents, photos, videos, audio) to a configured Telegram chat via a Telegram bot, with options for parse mode and silent notifications.
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 Notifier MCP Server
An MCP server that lets an LLM send messages and files to a user via a Telegram bot, to a single configured recipient. No external HTTP or Telegram libraries — just the native fetch API and the official MCP SDK.
Quick Start
Install dependencies with bun install --frozen-lockfile, then configure your MCP client to run the TypeScript source directly with Bun. No build step is required. The examples below use /absolute/path/to/telegram-notifier-mcp/src/index.ts; replace it with your checkout path. Do not use the published npm package to run these local changes.
1. Create a Telegram Bot
Open Telegram and message @BotFather
Send
/newbotand follow the prompts to name your botCopy the bot token you receive (e.g.,
123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)
2. Find Your Chat ID
Send any message to your new bot on Telegram
Open the following URL in your browser, replacing
YOUR_BOT_TOKENwith your actual token:https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdatesIn the JSON response, find
"chat":{"id": 123456789}— that number is your chat ID
Tip: For group chats, add the bot to the group, send a message, and check the same URL. Group chat IDs are negative numbers (e.g.,
-1001234567890).
3. Add to Your MCP Client
Claude Desktop
Add this to your Claude Desktop config file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"telegram-notifier": {
"command": "bun",
"args": ["/absolute/path/to/telegram-notifier-mcp/src/index.ts", "--chat-id=your-chat-id-here"],
"env": {
"TELEGRAM_BOT_TOKEN": "your-bot-token-here"
}
}
}
}Claude Code
Add to your project's .mcp.json or ~/.claude.json:
{
"mcpServers": {
"telegram-notifier": {
"command": "bun",
"args": ["/absolute/path/to/telegram-notifier-mcp/src/index.ts", "--chat-id=your-chat-id-here"],
"env": {
"TELEGRAM_BOT_TOKEN": "your-bot-token-here"
}
}
}
}Codex CLI
You can configure Codex CLI in either of these ways:
Option A: Add it manually in ~/.codex/config.toml
[mcp_servers.telegram-notifier]
command = "bun"
args = ["/absolute/path/to/telegram-notifier-mcp/src/index.ts", "--chat-id=your-chat-id-here"]
[mcp_servers.telegram-notifier.env]
TELEGRAM_BOT_TOKEN = "your-bot-token-here"Option B: Add it with a CLI command
codex mcp add telegram-notifier \
--env TELEGRAM_BOT_TOKEN=your-bot-token-here \
-- bun /absolute/path/to/telegram-notifier-mcp/src/index.ts --chat-id=your-chat-id-hereThat's it — your LLM can now send you Telegram notifications.
Related MCP server: telegram-mcp
Configuration
The recipient is fixed at startup using --chat-id=<numeric-id> (for example --chat-id=-1001234567890 for a group). TELEGRAM_CHAT_ID is supported as a fallback; the command-line argument takes precedence. Tool calls cannot override the recipient.
There are no incoming-message tools, polling, attachment downloads, or offset files.
Environment variables:
Variable | Required | Description |
| Yes | Bot token from @BotFather |
| Unless | Fixed numeric recipient chat ID. |
The server exits with an error if the bot token is missing or the recipient is missing or invalid.
Tools
send_message
Send a text message to a Telegram chat.
Parameter | Type | Required | Description |
| string | Yes | The message text to send |
| string | No |
|
| boolean | No | Send silently without notification sound |
send_document
Send a file/document to a Telegram chat.
Parameter | Type | Required | Description |
| string | Yes | Absolute path to the file |
| string | No | Caption for the document |
| string | No |
|
| boolean | No | Send silently without notification sound |
send_photo
Send a photo/image to a Telegram chat.
Parameter | Type | Required | Description |
| string | Yes | Absolute path to the image file |
| string | No | Caption for the photo |
| string | No |
|
| boolean | No | Send silently without notification sound |
send_video
Send a video to a Telegram chat.
Parameter | Type | Required | Description |
| string | Yes | Absolute path to the video file |
| string | No | Caption for the video |
| string | No |
|
| boolean | No | Send silently without notification sound |
send_audio
Send an audio file to a Telegram chat.
Parameter | Type | Required | Description |
| string | Yes | Absolute path to the audio file |
| string | No | Caption for the audio |
| string | No |
|
| boolean | No | Send silently without notification sound |
Testing with the MCP Inspector
You can test the server interactively using the MCP Inspector:
TELEGRAM_BOT_TOKEN="your-token" TELEGRAM_CHAT_ID="your-chat-id" \
bunx @modelcontextprotocol/inspector bun /absolute/path/to/telegram-notifier-mcp/src/index.tsThis opens a browser UI where you can invoke each tool and see the results.
Error Handling
The server handles errors gracefully and returns descriptive messages:
Scenario | Behavior |
Missing | Server exits at startup with instructions |
Missing or invalid startup chat ID | Server exits before connecting |
File not found | Returns |
File exceeds 50 MB | Returns |
Telegram API error | Returns |
All server logs go to stderr so they never interfere with the stdio MCP transport on stdout.
File Size Limits
Telegram enforces a 50 MB limit for file uploads via the Bot API. The server validates file size before uploading and returns an error if the limit is exceeded.
Development
git clone https://github.com/paulo-evangelista/telegram-notifier-mcp
cd telegram-notifier-mcp
bun install --frozen-lockfile
bun test
# Run with TELEGRAM_BOT_TOKEN set in the environment
bun run start --chat-id=123456789
# Watch mode — restarts on file changes
bun run dev --chat-id=123456789Publishing
Releases are published to npm automatically via GitHub Actions when you create a GitHub release.
Setup:
Add your npm token as a repository secret named
NPM_TOKENin GitHub Settings > Secrets and variables > ActionsBump the version in
package.jsonCreate a new GitHub release — the workflow will test and publish the Bun entry point to npm
License
MIT
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
Run a Telegram channel from your AI agent. Posts go out through your own bot, not your account.
Let AI assistants post to your Telegram chats, groups and channels. Not affiliated with Telegram.
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Messaging tools for AI agents: send messages, manage chats, groups and channels.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to send and receive messages, media, and files on Telegram, and manage chats via a bot token.1771 PyPIMIT
- AlicenseNot gradedqualityDmaintenanceEnables LLMs to send notifications and receive responses via Telegram.58 npm4MIT
- AlicenseBqualityDmaintenanceEnables AI agents to send notifications and media (text, photos, documents, videos) via a Telegram bot.4567 npm4Do What The F*ck You Want To Public
- FlicenseNot gradedqualityDmaintenanceEnables LLM clients to send messages, read recent messages, and retrieve chat information through the Telegram Bot API.-