MCP Telegram

Enable LLMs to control your Telegram

Connect Large Language Models to Telegram via the Model Context Protocol (MCP).

Built with Telethon, this server allows AI agents to interact with Telegram, enabling features like sending/editing/deleting messages, searching chats, managing drafts, downloading media, and more using the MTProto.

🚀 Getting Started

Prerequisites

• Python 3.10 or higher
• uv Install via the official uv guide.

Installation

Install the mcp-telegram CLI tool:

uv tool install mcp-telegram

⚙️ Usage

[!IMPORTANT] Please ensure you have read and understood Telegram's ToS before using this tool. Misuse of this tool may result in account restrictions.

The mcp-telegram command-line tool is your entry point.

mcp-telegram --help # See all commands

Login

First, authenticate with your Telegram account:

mcp-telegram login

This interactive command will prompt you for:

• API ID & API Hash: Obtain these from my.telegram.org/apps.
• Phone Number: Your Telegram-registered phone number (international format, e.g., +1234567890).
• Verification Code: Sent to your Telegram account upon first login.
• 2FA Password: If you have Two-Factor Authentication enabled.

Your credentials are securely stored in the session file for future use.

[!WARNING] Keep your API credentials private and never share them publicly

[!NOTE] Use mcp-telegram logout to logout from current session or mcp-telegram clear-session to remove all stored session data.

Connect to the MCP server

To use MCP Telegram with MCP clients like Claude Desktop or Cursor, you'll need to configure the MCP server. The configuration process varies by client and operating system.

For detailed setup instructions, please refer to:

• Claude Desktop MCP Setup Guide
• Cursor MCP Documentation

The configuration file should contain:

{
  "mcpServers": {
    "mcp-telegram": {
      "command": "mcp-telegram" /* Use full path if client can't find the command (e.g. "/usr/local/bin/mcp-telegram"). See IMPORTANT section below for full path instructions. */,
      "args": ["start"],
      "env": {
        "API_ID": "<your_api_id>",
        "API_HASH": "<your_api_hash>"
      }
    }
  }
}

[!Note] Configuration paths vary by OS and client. For example:

• macOS: `~/Library/Applic

... View full README on GitHub