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