tgbot-mcp
Provides tools for sending messages, structured notifications, action buttons, and waiting for replies via the Telegram Bot API.
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., "@tgbot-mcp Send a Telegram message: 'Deploy completed.'"
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.
tgbot-mcp
A trusted, open-source MCP (Model Context Protocol) server for Telegram.
Built as a clean alternative to closed-source or opaque Telegram MCP packages — bot token authentication only, no personal account access, no proprietary backend.
Features
Bot token auth only — uses the official Telegram Bot API (
api.telegram.org). Your personal account is never touched.4 purpose-built tools for LLM workflows: send messages, send structured notifications, send notifications with action buttons, and wait for user replies.
Language-agnostic — tools are written in English, but the LLM responds to users in their own language automatically. No language is hardcoded.
Smart polling in
wait_for_replyto minimise API calls while staying responsive.
Related MCP server: mcp-telegram
Quick Start
1. Create a Telegram Bot
Open Telegram and message @BotFather.
Send
/newbotand follow the prompts.Copy the bot token (looks like
123456:ABC-DEF...).Start a chat with your new bot, then visit:
https://api.telegram.org/bot<YOUR_TOKEN>/getUpdatesSend any message to the bot and look for
"chat":{"id":...}— that is your chat ID.
2. Register with Your MCP Client
Add the following to your MCP client configuration (e.g. claude_desktop_config.json):
{
"mcpServers": {
"tgbot-mcp": {
"command": "uvx",
"args": ["tgbot-mcp"],
"env": {
"TELEGRAM_BOT_TOKEN": "YOUR_BOT_TOKEN",
"TELEGRAM_CHAT_ID": "YOUR_CHAT_ID"
}
}
}
}uvx runs the server directly from PyPI without a separate install step. If you don't have uv yet:
curl -LsSf https://astral.sh/uv/install.sh | shAlternatively, install manually and run with
pip:pip install tgbot-mcpThen use
"command": "tgbot-mcp"(withoutuvx) in the config above.
Tools
send_message
Send a free-form text message to the configured chat.
Parameter | Type | Default | Description |
|
| (required) | Message body. Telegram Markdown supported. |
|
|
| Text formatting mode. |
Example prompt: "Send a Telegram message: 'Build finished successfully in 2m 14s.'"
send_notification
Send a structured notification with an automatic event emoji.
Event | Emoji |
| ✅ |
| ❌ |
| 🔄 |
| ❓ |
Parameter | Type | Default | Description |
|
| (required) | One of the four event types above. |
|
| (required) | One-line summary (≤200 chars). |
|
|
| Optional multi-line detail body. |
Example prompt: "Notify me on Telegram that the data pipeline completed. Include row counts."
send_notification_with_buttons
Send a notification with up to 4 inline action buttons. Ideal when you want the user to pick an option without typing.
Parameter | Type | Default | Description |
|
| (required) | Event type. |
|
| (required) | One-line summary. |
|
| (required) | 1–4 button labels. Each label is also the reply value. |
|
|
| Optional context text. |
Example prompt: "Ask me via Telegram whether to deploy to staging or production."
wait_for_reply
Block until the user replies (text message or button tap) or the timeout expires.
Parameter | Type | Default | Max | Description |
|
|
| no limit | How long to wait for a reply. |
Smart polling schedule:
Elapsed time | Poll interval |
0 – 10 minutes | 30 seconds |
10 minutes – 1 hr | 60 seconds |
1 hr+ | 120 seconds |
LLM guidelines for max_wait_seconds:
Scenario | Recommended value |
Simple yes/no question |
|
General task approval |
|
Stock price / event alert |
|
End-of-day review |
|
Overnight / long-running job |
|
Multi-day wait | any value — no limit |
Typical LLM Workflow
LLM: [does some long task]
→ send_notification_with_buttons(
event="question",
summary="Finished analysis. What should I do next?",
buttons=["📊 Generate report", "📧 Send email", "🔁 Re-run with new params"]
)
→ wait_for_reply(max_wait_seconds=1800)
→ [user taps "📊 Generate report"]
LLM: [generates the report]
→ send_notification(event="completed", summary="Report ready!", details="...")Environment Variables
Variable | Required | Description |
| ✅ | Bot token from @BotFather |
| ✅ | Chat ID to send messages to |
Development
# Clone and install in editable mode
git clone https://github.com/TGLEEEE/tgbot-mcp
cd tgbot-mcp
pip install -e ".[dev]"
# Run directly
TELEGRAM_BOT_TOKEN=... TELEGRAM_CHAT_ID=... python -m tgbot_mcp.serverSecurity
Only the official Telegram Bot API is used (
api.telegram.org). No third-party relay.Bot tokens are read from environment variables — never hardcoded.
Only the chat configured via
TELEGRAM_CHAT_IDreceives messages.No personal Telegram account credentials are ever required.
License
MIT — see LICENSE.
Available Tools
4 toolssend_messageA
Send a free-form text message to the configured Telegram chat.
Use this for casual messages, inline code snippets, status updates, or any content that does not require structured formatting.
Args: text : The message body. Supports Telegram Markdown v1 by default. parse_mode : 'Markdown', 'HTML', or '' for plain text. Default: 'Markdown'.
Inputs: text (required), parse_mode. Returns: result
send_notificationA
Send a structured notification to the configured Telegram chat.
Automatically prepends an emoji for quick visual scanning. Default emojis by event type: completed → ✅ error → ❌ progress → 🔄 question → ❓
Override the default emoji with the icon parameter when the context calls for something more specific (e.g. icon='🚀' for a deployment, '🧪' for a test run, '📊' for a report).
Args: event : Event type — 'completed', 'error', 'progress', or 'question'. summary : One-line summary shown prominently (≤200 chars recommended). details : Optional multi-line body — stack traces, next steps, metrics, etc. icon : Optional emoji to override the default event icon.
Inputs: event (required), summary (required), details, icon. Returns: result
send_notification_with_buttonsA
Send a structured notification with up to 4 inline action buttons.
Buttons let the user reply with a single tap instead of typing. After sending, call wait_for_reply to capture the chosen button or typed reply.
Button design guidelines:
Provide 2–4 buttons with clear, action-oriented labels.
Keep each label under 30 characters.
Buttons are suggestions — users can always type a custom reply instead.
Use emoji prefixes in labels to aid scannability (e.g. '✅ Approve', '❌ Cancel').
Args: event : Event type — 'completed', 'error', 'progress', or 'question'. summary : One-line summary (≤200 chars). buttons : List of 1–4 button label strings. Each label becomes the button text AND the callback payload. details : Optional additional context or instructions for the user. icon : Optional emoji to override the default event icon.
Inputs: event (required), summary (required), buttons (required), details, +1 more. Returns: result
wait_for_replyA
Wait for a reply from the user via Telegram and return it.
Handles both plain text messages and inline button taps (callback queries).
Smart polling intervals (minimises API calls): 0 – 10 min elapsed → poll every 30 s 10 min – 1 hr → poll every 60 s 1 hr+ → poll every 120 s
LLM guidelines for choosing max_wait_seconds: Simple yes/no or quick question → 300 (5 min) General task approval → 1 800 (30 min) ← default Stock price / alert trigger → 1 800 (30 min) End-of-day review → 7 200 (2 hr) Overnight / long-running job → 86 400 (24 hr) Multi-day wait → any value — no maximum
Args: max_wait_seconds : How long to wait. Default 1800, no upper limit. Pick a value appropriate to how soon a reply is expected.
Inputs: max_wait_seconds. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a distinct purpose: free-form text, structured notification, notification with buttons, and waiting for replies. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern with underscores (send_message, send_notification, send_notification_with_buttons, wait_for_reply).
With only 4 tools, the set is minimal but appropriately scoped for a Telegram bot focused on sending messages and awaiting replies. Slightly thin but not inadequate.
The core interaction loop (send message, structured notification with/without buttons, wait for reply) is covered. Missing features like message editing or history are minor gaps.
Related MCP Connectors
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Hosted Telegram MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
MCP server for AI dialogue using various LLM models via AceDataCloud
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables interaction with Telegram to send, read, and search messages across chats and dialogs. It supports waiting for incoming messages and retrieving conversation history through natural language commands.17 npm3MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that wraps the Telegram Bot API into semantic tools for LLM agents, supporting multi-bot management for sending and receiving messages. It enables agents to send text, photos, and documents, as well as fetch recent updates from multiple configured Telegram bots.MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server enabling AI agents to interact with users via Telegram, supporting message and image sending, inline quick replies, and waiting for user responses.9 npmMIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server for sending and receiving Telegram messages via a bot, enabling AI assistants to interact directly through Telegram by sending messages, reading recent messages, and sending photos.-