agent-telegram-mcp

agent-telegram-mcp

A robust Model Context Protocol (MCP) server that enables AI agents to seamlessly interact with Telegram using a standard Bot Token. It provides a comprehensive suite of tools for bidirectional communication, including sending and receiving text messages, multimedia, documents, and managing chats.

Installation

Install using pip or uv:

pip install agent-telegram-mcp

or

uv tool install agent-telegram-mcp

Configuration

This MCP server requires a Telegram Bot Token. You can create a new bot and obtain your token by talking to the BotFather on Telegram.

To use this server with MCP-compatible clients (like Claude Desktop, Agent_head, etc.), add it to your server configuration and pass the token as an environment variable:

Example mcp_config.json

{
  "mcpServers": {
    "agent-telegram-mcp": {
      "command": "agent-telegram-mcp",
      "env": {
        "TELEGRAM_BOT_TOKEN": "123456789:ABCdefGHIjklMNOpqrSTUvwxYZ"
      }
    }
  }
}

Available Tools

The server exposes the following tools to the LLM agent:

✉️ Messaging

• telegram_send_message: Send text messages (supports Markdown, HTML, silent messages, and replies).
• telegram_forward_message: Forward existing messages between chats.
• telegram_delete_message: Delete a message from a chat (requires bot admin permissions).
• telegram_pin_message: Pin a message in a group/channel.

🖼️ Media & Files

• telegram_send_photo: Send images via a local file path, public HTTP URL, or Telegram file ID.
• telegram_send_video: Send video files.
• telegram_send_audio: Send audio tracks (renders as a Telegram music player).
• telegram_send_voice: Send voice notes (.ogg files).
• telegram_send_document: Send arbitrary files (PDFs, ZIPs, code snippets, etc.).
• telegram_send_sticker: Send .webp stickers.
• telegram_send_location: Send a geographic map pin via latitude and longitude.

📥 Retrieval & Info

• telegram_get_updates: Retrieve recent messages, commands, and callback queries sent to the bot (supports pagination with offset and limit).
• telegram_get_chat_info: Fetch detailed information about a user, group, or channel.
• telegram_get_chat_member_count: Check how many users are in a chat.
• telegram_get_file_info: Retrieve metadata and the download path for a file hosted on Telegram servers.
• telegram_download_file: Download a file to a specific local path or return its contents as a Base64 string.
• telegram_get_bot_info: Fetch the current bot's profile information to verify the token connection.

Development & Testing

You can run the server directly via standard I/O (stdio) transport:

export TELEGRAM_BOT_TOKEN="your-token"
# On Windows: set TELEGRAM_BOT_TOKEN=your-token

agent-telegram-mcp