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. - Zero external services. Pure Python + httpx + fastmcp.
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:
Send any message to the bot and look forhttps://api.telegram.org/bot<YOUR_TOKEN>/getUpdates"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 | sh
Alternatively, 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 |
|---|---|---|---|
text |
str |
(required) | Message body. Telegram Markdown supported. |
parse_mode |
"Markdown" | "HTML" | "" |
"Markdown" |
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 |
|---|---|
completed |
✅ |
error |
❌ |
progress |
🔄 |
question |
❓ |
| Parameter | Type | Default | Description |
|---|---|---|---|
event |
str |
(required) | One of the four event types above. |
summary |
str |
(required) | One-line summary (≤200 chars). |
details |
str |
"" |
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 |
|---|---|---|---|
event |
str |
(required) | Event type. |
summary |
str |
(required) | One-line summary. |
buttons |
list[str] |
(required) | 1–4 button labels. Each label is also the reply value. |
details |
str |
"" |
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 |
|---|---|---|---|---|
max_wait_seconds |
int |
1800 |
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 | 300 (5 min) |
| General task approval | 1800 (30 min) ✓ |
| Stock price / event alert | 1800 (30 min) |
| End-of-day review | 7200 (2 hr) |
| Overnight / long-running job | 86400 (24 hr) |
| 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 |
|---|---|---|
TELEGRAM_BOT_TOKEN |
✅ | Bot token from @BotFather |
TELEGRAM_CHAT_ID |
✅ | 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.server
Security
- 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.
Metadata
Release files for tgbot-mcp 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tgbot_mcp-0.1.2.tar.gz | 8.0 kB | Without provenance | Details for tgbot_mcp-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tgbot_mcp-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for tgbot_mcp-0.1.2-py3-none-any.whl |
Total release size: 17.4 kB
Release files / tgbot_mcp-0.1.2.tar.gz
| Download URL | tgbot_mcp-0.1.2.tar.gz |
|---|---|
| Size | 8.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
99d959a80fa7d61834cd586ef3c4f23d496d4bafe22e6eb9d175319162228477
|
|
BLAKE2b-256 checksum How to use checksums |
8bfdaaff3c725eb6192fc5d08d2609d1544fc4d016e7ab5dd6fd00c64eabd092
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Release files / tgbot_mcp-0.1.2-py3-none-any.whl
| Download URL | tgbot_mcp-0.1.2-py3-none-any.whl |
|---|---|
| Size | 9.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
72e13fcd6a60acbf928b2d0d2991f263534309fdba2a299741cd7574eec0f8d9
|
|
BLAKE2b-256 checksum How to use checksums |
f7a6673386e4328746c10bdf9662864a00a26b28b6a27aa5d79772d7884ca474
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Security for tgbot-mcp 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.