Connect Large Language Models to Telegram via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction).
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.
- Getting Started
- [ Usage](# -usage)
- Available Tools
- [ Troubleshooting](# -troubleshooting)
- Contributing
- License
Getting Started
Prerequisites
- Python 3.10 or higher
- `uv` Install via the official uv guide.
Installation
Install the
mcp-telegram CLI tool:Usage
[!IMPORTANT] 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.Login
First, authenticate with your Telegram account:
This 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] Usemcp-telegram logoutto logout from current session ormcp-telegram clear-sessionto remove all stored session data.
Connect to the MCP server
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:
[!Note] Configuration paths vary by OS and client. For example:
[!IMPORTANT] If your client cannot executemcp-telegramdespite it being accessible in the terminal, try using the full path to the executable. You can find this by runningwhich mcp-telegram(macOS/Linux) orwhere mcp-telegram(Windows) in your terminal. Replace thecommandvalue in the configuration with the full path.
After saving the configuration file, restart your application.
Available Tools
Here's a comprehensive list of tools you can use to interact with Telegram through MCP:
Messaging Tools
[object Object] | [object Object] |
[object Object] | [object Object] |
[object Object] | [object Object] |
[object Object] | [object Object] |
[object Object] | [object Object] |
Search & Navigation
[object Object] | [object Object] |
[object Object] | [object Object] |
[object Object] | [object Object] |
Draft Management
[object Object] | [object Object] |
[object Object] | [object Object] |
[object Object] | [object Object] |
Media Handling
[object Object] | [object Object] |
[object Object] | [object Object] |
[!Note] For detailed parameter information and example use cases, runmcp-telegram toolsin your terminal.
Troubleshooting
Database Locked Errors
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.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)
Contributing
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.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Connect Large Language Models to Telegram via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction).
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.
- Getting Started
- [ Usage](# -usage)
- Available Tools
- [ Troubleshooting](# -troubleshooting)
- Contributing
- License
Getting Started
Prerequisites
- Python 3.10 or higher
- `uv` Install via the official uv guide.
Installation
Install the
mcp-telegram CLI tool:Usage
[!IMPORTANT] 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.Login
First, authenticate with your Telegram account:
This 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] Usemcp-telegram logoutto logout from current session ormcp-telegram clear-sessionto remove all stored session data.
Connect to the MCP server
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:
[!Note] Configuration paths vary by OS and client. For example:
[!IMPORTANT] If your client cannot executemcp-telegramdespite it being accessible in the terminal, try using the full path to the executable. You can find this by runningwhich mcp-telegram(macOS/Linux) orwhere mcp-telegram(Windows) in your terminal. Replace thecommandvalue in the configuration with the full path.
After saving the configuration file, restart your application.
Available Tools
Here's a comprehensive list of tools you can use to interact with Telegram through MCP:
Messaging Tools
[object Object] | [object Object] |
[object Object] | [object Object] |
[object Object] | [object Object] |
[object Object] | [object Object] |
[object Object] | [object Object] |
Search & Navigation
[object Object] | [object Object] |
[object Object] | [object Object] |
[object Object] | [object Object] |
Draft Management
[object Object] | [object Object] |
[object Object] | [object Object] |
[object Object] | [object Object] |
Media Handling
[object Object] | [object Object] |
[object Object] | [object Object] |
[!Note] For detailed parameter information and example use cases, runmcp-telegram toolsin your terminal.
Troubleshooting
Database Locked Errors
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.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)
Contributing
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.
License
This project is licensed under the MIT License - see the LICENSE file for details.