sparfenyuk/mcp-telegram

Telegram MCP server
About
What is MCP?
What does this server do?
Practical use cases
Prerequisites
Installation
Configuration
Telegram API Configuration
Claude Desktop Configuration
Telegram Configuration
Development
Getting started
Debugging the server in terminal
Debugging the server in the Inspector
Troubleshooting
Message 'Could not connect to MCP server mcp-telegram'
## 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.
[x] Get the list of dialogs (chats, channels, groups)
[x] 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
[x] 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
uv tool
## Installation
bash
uv tool install git+https://github.com/sparfenyuk/mcp-telegram
> [!NOTE]
> If you have already installed the server, you can update it using uv tool upgrade --reinstall command.
> [!NOTE]
> If you want to delete the server, use the uv tool uninstall mcp-telegram command.
## Configuration
### Telegram API Configuration
Before you can use the server, you need to connect to the Telegram API.
1. Get the API ID and hash from Telegram API
2. Run the following command:
bash
mcp-telegram sign-in --api-id --api-hash --phone-number
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 the mcp-telegram logout command.
### Claude Desktop Configuration
Configure Claude Desktop to recognize the Exa MCP server.
1. Open the Claude Desktop configuration file:
in MacOS, the configuration file is located at ~/Library/Application Support/Claude/claude_desktop_config.json
in Windows, the configuration file is located at %APPDATA%\Claude\claude_desktop_config.json
> __Note:__
> You can also find claude_desktop_config.json inside the settings of Claude Desktop app
2. Add the server configuration
json
"mcpServers": {
"mcp-telegram": {
"command": "mcp-server",
"env": {
"TELEGRAM_API_ID": " ",
"TELEGRAM_API_HASH": " ",
},
### Telegram Configuration
Before working with Telegram’s API, you need to get your own API ID and hash:
1. Login to your Telegram account with the phone number of the developer account to use.
1. Click under API Development tools.