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

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

Related MCP server: telegram-mcp

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.

Example prompt: "Send a Telegram message: 'Build finished successfully in 2m 14s.'"

send_notification

Send a structured notification with an automatic event emoji.

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.

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.

Smart polling schedule:

LLM guidelines for max_wait_seconds:

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

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.