chaindead/telegram-mcp

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.
Table of Contents
- What is MCP?
- What does this server do?
- Capabilities
- Prompt examples
- Message Management
- Organization
- Communication
- Installation
- Homebrew
- NPX
- From Releases
- MacOS
- Linux
- Windows
- From Source
- Configuration
- Authorization
- Client Configuration
- JSON Schema Version
- Star History
What is MCP?
The Model Context Protocol (MCP) is a system that lets AI apps, like Claude Desktop or Cursor, 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?
Capabilities
- [x] Get current account information (tool: tg_me)
- [x] List dialogs with optional unread filter (tool: tg_dialogs)
- [x] Mark dialog as read (tool: tg_read)
- [x] Retrieve messages from specific dialog (tool: tg_dialog)
- [x] Send draft messages to any dialog (tool: tg_send)
Prompt examples
Here are some example prompts you can use with AI assistants:
Message Management
- "Check for any unread important messages in my Telegram"
- "Summarize all my unread Telegram messages"
- "Read and analyze my unread messages, prepare draft responses where needed"
- "Check non-critical unread messages and give me a brief overview"
Organization
- "Analyze my Telegram dialogs and suggest a folder structure"
- "Help me categorize my Telegram chats by importance"
- "Find all work-related conversations and suggest how to organize them"
Communication
- "Monitor specific chat for updates about [topic]"
- "Draft a polite response to the last message in [chat]"
- "Check if there are any unanswered questions in my chats"
Installation
Homebrew
You can install a binary release on macOS/Linux using brew:
NPX
You can run the latest version directly using npx (supports macOS, Linux, and Windows):
When using NPX, modify the standard commands and configuration as follows:
- Authentication command becomes:
- Claude MCP server configuration becomes:
For complete setup instructions, see Authorization and Client Configuration.
From Releases
MacOS
> **Note:** The commands below install to /usr/local/bin. To install elsewhere, replace /usr/local/bin with your preferred directory in your PATH.
First, download the archive for your architecture:
Then install the binary:
Linux
> **Note:** The commands below install to /usr/local/bin. To install elsewhere, replace /usr/local/bin with your preferred directory in your PATH.
First, download the archive for your architecture:
Then install the binary:
Windows
Windows
1. Download the latest release for your architecture:
- Windows x64
- Windows ARM64
2. Extract the .zip file
3. Add the extracted directory to your PATH or move telegram-mcp.exe to a directory in your PATH