telegram

This Telegram MCP server provides a comprehensive Telethon-powered integration for Claude, Cursor, and any MCP-compatible client. It exposes a wide range of Telegram tools as MCP functions, covering chat and group management, messaging, contact management, user profiles, media handling, searches, and governance tasks. You can query chats, send messages, manage groups and channels, handle invites, export/import contacts, work with polls, pins, reactions, and even inspect or trigger inline keyboard buttons. The server is designed to be consumed by MCP clients that can enumerate and call these tool APIs, enabling automation and conversational access to Telegram features through the MCP protocol.

Prerequisites:

• Python 3.8+ (recommended)
• pip (Python package manager)
• Access to Telegram API credentials (API ID, API Hash) and a bot token or a session-configured account

Installation steps:

1. Install Python if not already installed
2. Create and activate a virtual environment (optional but recommended)
   • python -m venv venv
   • source venv/bin/activate # on Unix/macOS
   • .\venv\Scripts\activate # on Windows
3. Install the Telegram MCP package (adjust package name if different in your repo)
   • pip install telegram-mcp
4. Configure environment variables with your Telegram credentials
   • On Unix/macOS: export TELEGRAM_API_ID=your_api_id export TELEGRAM_API_HASH=your_api_hash export TELEGRAM_BOT_TOKEN=your_bot_token export TELEGRAM_SESSION_NAME=telegram_mcp_session
   • On Windows (PowerShell): $env:TELEGRAM_API_ID = 'your_api_id' $env:TELEGRAM_API_HASH = 'your_api_hash' $env:TELEGRAM_BOT_TOKEN = 'your_bot_token' $env:TELEGRAM_SESSION_NAME = 'telegram_mcp_session'
5. Run the MCP server (example using the Python module entry point)
   • python -m telegram_mcp
6. Verify the server starts and is reachable by your MCP client

Optional: If you prefer Docker, you can containerize this setup by creating a Dockerfile that installs Python and telegram-mcp and passes the required environment variables at runtime.

Environment variables are required for Telegram authentication (API ID/Hash and a bot token or session). Ensure you keep these credentials secure. The MCP server exposes a large suite of tools; you can selectively enable or disable features via your client configuration or by adjusting the package's internal access controls. If you encounter connection issues, verify that the Telegram credentials are valid and that your hosting environment allows outbound connections to Telegram servers. For long-running deployments, consider mounting a persistent session file (named via TELEGRAM_SESSION_NAME) to maintain login state across restarts.