This project provides a Telegram server that implements the Model Context Protocol (MCP), enabling AI assistants like Claude and Cursor to interact with your Telegram account. It offers a comprehensive suite of tools for managing chats, messages, contacts, and user profiles, automating Telegram tasks through natural language commands.

How It Works

The server leverages the Telethon library to interface with the Telegram API. It exposes Telegram functionalities as callable "tools" that MCP-compatible clients can invoke. This allows AI models to understand user requests, translate them into specific Telegram actions (e.g., sending a message, creating a group), and execute them via the Telethon backend.

Quick Start & Requirements

• Installation: Clone the repository, create a virtual environment, install dependencies (pip install -r requirements.txt), generate a session string (python session_string_generator.py), and configure .env with Telegram API credentials.
• Prerequisites: Python 3.10+, Telethon, MCP Python SDK, and an MCP client (Claude Desktop or Cursor).
• Docker: A Dockerfile and docker-compose.yml are provided for containerized deployment.
• Setup Time: Estimated setup time is minimal, primarily involving credential configuration.
• Documentation: Examples and usage guides are available within the README.

Highlighted Details

• Extensive toolset covering chat management, messaging, contact operations, user profile updates, and media retrieval.
• Robust error handling with detailed logging to mcp_errors.log.
• Support for both file-based and session string authentication.
• Fallback mechanisms for critical functions like retrieving invite links.
• Removed file-attachment related tools (send_file, download_media, etc.) and GIF tools due to MCP environment limitations and Telethon reliability issues.

Maintenance & Community

Maintained by @chigwell and @l1v0n1. Pull requests are welcome.

Licensing & Compatibility

Licensed under the Apache 2.0 License. This license is permissive and generally compatible with commercial and closed-source applications.

Limitations & Caveats

Tools requiring direct file path access (e.g., send_file, download_media) and GIF-related tools have been removed. The project relies on Telethon, which may have its own limitations or changes affecting functionality.