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.
Table of Contents
- Python 3.10 or higher
uvInstall via the official uv guide.
Install the mcp-telegram CLI tool:
uv tool install mcp-telegramImportant
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 commandsFirst, authenticate with your Telegram account:
mcp-telegram loginThis 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.
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:
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/Application Support/Claude/or~/.cursor/ - Windows:
%APPDATA%\Claude\or%APPDATA%\Cursor\
Important
If your client cannot execute mcp-telegram despite it being accessible in the terminal, try using the full path to the executable. You can find this by running which mcp-telegram (macOS/Linux) or where mcp-telegram (Windows) in your terminal. Replace the command value in the configuration with the full path.
After saving the configuration file, restart your application.
Here's a comprehensive list of tools you can use to interact with Telegram through MCP:
| Tool | Description |
|---|---|
send_message |
✉️ Send text messages or files to any user, group, or channel |
edit_message |
✏️ Modify content of previously sent messages |
delete_message |
🗑️ Remove one or multiple messages |
get_messages |
📜 Retrieve message history with advanced filtering options |
| Tool | Description |
|---|---|
search_dialogs |
🔎 Find users, groups, and channels by name or username |
message_from_link |
🔗 Access specific messages using Telegram links |
| Tool | Description |
|---|---|
get_draft |
📋 View current message draft for any chat |
set_draft |
✍️ Create or clear message drafts |
| Tool | Description |
|---|---|
media_download |
📸 Download photos, videos, and documents from messages |
Note
For detailed parameter information and example use cases, run mcp-telegram tools in your terminal.
Running multiple mcp-telegram instances using the same session file can cause database is locked errors due to Telethon's SQLite session storage. Ensure only one instance uses a session file at a time.
Force-Stopping Existing Processes
If you need to stop potentially stuck processes:
- macOS / Linux:
pkill -f "mcp-telegram" - Windows:
taskkill /F /IM mcp-telegram.exe /T(Check Task Manager for the exact process name)
We welcome contributions! If you'd like to help improve MCP Telegram, please feel free to submit issues, feature requests, or pull requests. Your feedback and contributions help make this project better for everyone.
This project is licensed under the MIT License - see the
Made with ❤️ by Yeabsira Driba