Skip to main content
Glama
tgbot-mcp
by TGLEEEE

tgbot-mcp

PyPI version Python License: MIT

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_reply to minimise API calls while staying responsive.

  • Zero external services. Pure Python + httpx + fastmcp.


Related MCP server: mcp-telegram

Quick Start

1. Create a Telegram Bot

  1. Open Telegram and message @BotFather.

  2. Send /newbot and follow the prompts.

  3. Copy the bot token (looks like 123456:ABC-DEF...).

  4. Start a chat with your new bot, then visit:

    https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates

    Send 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 | sh

Alternatively, install manually and run with pip:

pip install tgbot-mcp

Then use "command": "tgbot-mcp" (without uvx) 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_ID receives messages.

  • No personal Telegram account credentials are ever required.


License

MIT — see LICENSE.

Available Tools

4 tools
send_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

    A4.4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a distinct purpose: free-form text, structured notification, notification with buttons, and waiting for replies. No overlap or ambiguity.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with underscores (send_message, send_notification, send_notification_with_buttons, wait_for_reply).

    Tool Count4/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      An 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.
      -