Telegram MCP server
- Telegram MCP server
About
The server is a bridge between the Telegram API and the AI assistants and is based on the Model Context Protocol.
[!IMPORTANT] Ensure that you have read and understood the Telegram API Terms of Service before using this server. Any misuse of the Telegram API may result in the suspension of your account.
What is MCP?
The Model Context Protocol (MCP) is a system that lets AI apps, like Claude Desktop, connect to external tools and data sources. It gives a clear and safe way for AI assistants to work with local services and APIs while keeping the user in control.
What does this server do?
As of not, the server provides read-only access to the Telegram API.
- Get the list of dialogs (chats, channels, groups)
- Get the list of (unread) messages in the given dialog
- Mark chanel as read
- Retrieve messages by date and time
- Download media files
- Get the list of contacts
- Draft a message
- ...
Practical use cases
- Create a summary of the unread messages
- Find contacts with upcoming birthdays and schedule a greeting
- Find discussions on a given topic, summarize them and provide a list of links
Prerequisites
Installation
[!NOTE] If you have already installed the server, you can update it usinguv tool upgrade --reinstallcommand.
[!NOTE] If you want to delete the server, use theuv tool uninstall mcp-telegramcommand.
Configuration
Telegram API Configuration
Before you can use the server, you need to connect to the Telegram API.
- Get the API ID and hash from Telegram API
- Run the following command:Enter the code you received from Telegram to connect to the API.The password may be required if you have two-factor authentication enabled.
[!NOTE] To log out from the Telegram API, use themcp-telegram logoutcommand.
Claude Desktop Configuration
Configure Claude Desktop to recognize the Exa MCP server.
- Open the Claude Desktop configuration file:
- Add the server configuration
Telegram Configuration
Before working with Telegram s API, you need to get your own API ID and hash:
- Login to your Telegram account with the phone number of the developer account to use.
- Click under API Development tools.
- A 'Create new application' window will appear. Fill in your application details. There is no need to enter any URL, and only the first two fields (App title and Short name) can currently be changed later.
- Click on 'Create application' at the end. Remember that your API hash is secret and Telegram won t let you revoke it. Don t post it anywhere!
Development
Getting started
- Clone the repository
- Install the dependencies
- Run the server
Tools can be added to the
src/mcp_telegram/tools.py file.How to add a new tool:
- Create a new class that inherits from ToolArgsAttributes of the class will be used as arguments for the tool. The class docstring will be used as the tool description.
- Implement the tool_runner function for the new classThe function should return a sequence of TextContent, ImageContent or EmbeddedResource. The function should be async and accept a single argument of the new class.
- Done! Restart the client and the new tool should be available.
Validation can accomplished either through Claude Desktop or by running the tool directly.
Debugging the server in terminal
To run the tool directly, use the following command:
Debugging the server in the Inspector
The MCP inspector is a tool that helps to debug the server using fancy UI. To run it, use the following command:
[!WARNING] Do not forget to define Environment Variables TELEGRAM_API_ID and TELEGRAM_API_HASH in the inspector.
Troubleshooting
Message 'Could not connect to MCP server mcp-telegram'
If you see the message 'Could not connect to MCP server mcp-telegram' in Claude Desktop, it means that the server configuration is incorrect.
Try the following:
- Use the full path to the
uvbinary in the configuration file
- Check the path to the cloned repository in the configuration file
Telegram MCP server
- Telegram MCP server
About
The server is a bridge between the Telegram API and the AI assistants and is based on the Model Context Protocol.
[!IMPORTANT] Ensure that you have read and understood the Telegram API Terms of Service before using this server. Any misuse of the Telegram API may result in the suspension of your account.
What is MCP?
The Model Context Protocol (MCP) is a system that lets AI apps, like Claude Desktop, connect to external tools and data sources. It gives a clear and safe way for AI assistants to work with local services and APIs while keeping the user in control.
What does this server do?
As of not, the server provides read-only access to the Telegram API.
- Get the list of dialogs (chats, channels, groups)
- Get the list of (unread) messages in the given dialog
- Mark chanel as read
- Retrieve messages by date and time
- Download media files
- Get the list of contacts
- Draft a message
- ...
Practical use cases
- Create a summary of the unread messages
- Find contacts with upcoming birthdays and schedule a greeting
- Find discussions on a given topic, summarize them and provide a list of links
Prerequisites
Installation
[!NOTE] If you have already installed the server, you can update it usinguv tool upgrade --reinstallcommand.
[!NOTE] If you want to delete the server, use theuv tool uninstall mcp-telegramcommand.
Configuration
Telegram API Configuration
Before you can use the server, you need to connect to the Telegram API.
- Get the API ID and hash from Telegram API
- Run the following command:Enter the code you received from Telegram to connect to the API.The password may be required if you have two-factor authentication enabled.
[!NOTE] To log out from the Telegram API, use themcp-telegram logoutcommand.
Claude Desktop Configuration
Configure Claude Desktop to recognize the Exa MCP server.
- Open the Claude Desktop configuration file:
- Add the server configuration
Telegram Configuration
Before working with Telegram s API, you need to get your own API ID and hash:
- Login to your Telegram account with the phone number of the developer account to use.
- Click under API Development tools.
- A 'Create new application' window will appear. Fill in your application details. There is no need to enter any URL, and only the first two fields (App title and Short name) can currently be changed later.
- Click on 'Create application' at the end. Remember that your API hash is secret and Telegram won t let you revoke it. Don t post it anywhere!
Development
Getting started
- Clone the repository
- Install the dependencies
- Run the server
Tools can be added to the
src/mcp_telegram/tools.py file.How to add a new tool:
- Create a new class that inherits from ToolArgsAttributes of the class will be used as arguments for the tool. The class docstring will be used as the tool description.
- Implement the tool_runner function for the new classThe function should return a sequence of TextContent, ImageContent or EmbeddedResource. The function should be async and accept a single argument of the new class.
- Done! Restart the client and the new tool should be available.
Validation can accomplished either through Claude Desktop or by running the tool directly.
Debugging the server in terminal
To run the tool directly, use the following command:
Debugging the server in the Inspector
The MCP inspector is a tool that helps to debug the server using fancy UI. To run it, use the following command:
[!WARNING] Do not forget to define Environment Variables TELEGRAM_API_ID and TELEGRAM_API_HASH in the inspector.
Troubleshooting
Message 'Could not connect to MCP server mcp-telegram'
If you see the message 'Could not connect to MCP server mcp-telegram' in Claude Desktop, it means that the server configuration is incorrect.
Try the following:
- Use the full path to the
uvbinary in the configuration file
- Check the path to the cloned repository in the configuration file