Overview
What is Telegram?
Telegram is an MCP (Model Context Protocol) server that enables AI agents and other MCP clients to interact with the Telegram messaging platform. It provides a bridge between the Telegram API and MCP-compatible tools, allowing automated reading of dialogs and messages, sending messages, and executing arbitrary Telegram methods using a user’s Telegram account.
How to use Telegram?
To use Telegram, clone the repository, install dependencies with npm install, create a .env file with your API_ID and API_HASH from my.telegram.org, and run the server with npm run mcp or node mcp-server.js. The server can then be configured in MCP clients such as Cursor or Claude Desktop by pointing to the server’s command (e.g., node /full/path/to/project/mcp-server.js). On first use, the server prompts for a phone number and a confirmation code (and a 2FA password if enabled).
Key features of Telegram
- Reads dialogs and messages from your Telegram account.
- Sends messages to any chat or user.
- Executes arbitrary Telegram API methods via
executeMethod. - Saves authenticated sessions locally for reuse.
- Supports two-factor authentication (2FA).
- Integrates easily with MCP clients like Cursor and Claude Desktop.
Use cases of Telegram
- An AI assistant fetching recent chats and sending replies on a user’s behalf.
- Automated message broadcasting to a Telegram channel or group.
- Retrieving message history for analysis or logging.
- Executing custom Telegram API calls to manage contacts, groups, or bots.
- Building conversational agents that operate through Telegram.
FAQ from Telegram
What are the requirements to run Telegram?
You need Node.js 14+ (or higher), npm, a Telegram API ID and API Hash obtained from my.telegram.org, and a Telegram account for authentication.
How are sessions stored?
Sessions are saved as JSON files inside the sessions/ directory, named after the phone number (e.g., +79001234567.json). Each file contains an encrypted authorization token and a timestamp.
What happens during first-time authorization?
The server asks for the phone number, then a confirmation code sent by Telegram. If two-factor authentication is enabled, the password is requested (up to 3 retries). Successful authorization saves the session for future use.
Can I use arbitrary Telegram API methods?
Yes, the executeMethod tool allows executing any Telegram API method. Use it with caution as it can perform destructive actions.
What authentication does Telegram support?
The server uses the user’s phone number and confirmation code for initial auth, and supports two-factor authentication (2FA) passwords when enabled. Multi‑session handling is supported via the session parameter (the phone number).
