Overview
What is Telegram MCP Server?
A Telegram integration server that provides tools for managing contacts, sending messages, and retrieving channel information through the MCP (Multi-Client Protocol). It is designed for users who want to automate Telegram interactions using a local MCP client.
How to use Telegram MCP Server?
Install Python 3.8+ and Node.js 14+. Clone the repository, create a virtual environment with uv venv, activate it, and run uv pip install. Create a .env file with your Telegram API credentials (TG_API_ID, TG_API_HASH, phone). Integrate with Cursor or Claude Desktop by placing the provided JSON configuration in the appropriate config file, substituting the paths from which uv and pwd. Once configured, you can call tools like get_contacts(), send_message_by_identifier(), get_chat_history(), and get_channel_posts().
Key features of Telegram MCP Server
- Contact management: list, search, and view last interactions
- Send messages to contacts by name or phone number
- Retrieve chat history with date range filtering
- Get posts from channels with optional date filtering
- Search channels and view channel information
- Comprehensive error handling for invalid credentials, network issues, and rate limiting
Use cases of Telegram MCP Server
- Automate sending messages to multiple contacts
- Monitor and archive recent conversations
- Fetch and analyze posts from Telegram channels
- Retrieve interaction history for customer support or personal records
FAQ from Telegram MCP Server
What prerequisites are needed to run Telegram MCP Server?
Python 3.8 or higher, Node.js 14 or higher, a Telegram account, and Telegram API credentials (api_id and api_hash).
How do I obtain Telegram API credentials?
The README states you need api_id and api_hash but does not detail how to get them. You must obtain them from Telegram’s developer platform.
Is there built‑in rate limiting protection?
Yes, the server includes error handling for rate limiting, along with invalid credentials, network issues, invalid parameters, and permission errors.
What are the available tools?
get_contacts(), send_message_by_identifier(identifier, message), get_last_interaction(identifier), get_chat_history(identifier, start_date, end_date, limit), and get_channel_posts(channel_name, start_date, end_date, limit).
What libraries does this server depend on?
It uses the Telethon library for Telegram API integration and FastMCP for the server framework.
