Telegram MCP server

1[![](https://badge.mcpx.dev?type=server 'MCP Server')](https://github.com/punkpeye/awesome-mcp-servers?tab=readme-ov-file#communication)
2[![](https://img.shields.io/badge/OS_Agnostic-Works_Everywhere-purple)](https://github.com/chaindead/telegram-mcp?tab=readme-ov-file#installation)
3[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
4[![Visitors](https://api.visitorbadge.io/api/visitors?path=https%3A%2F%2Fgithub.com%2Fchaindead%2Ftelegram-mcp&label=Visitors&labelColor=%23d9e3f0&countColor=%23697689&style=flat&labelStyle=none)](https://visitorbadge.io/status?path=https%3A%2F%2Fgithub.com%2Fchaindead%2Ftelegram-mcp)
5 
6# Telegram MCP server
7 
8The server is a bridge between the Telegram API and the AI assistants and is based on the [Model Context Protocol](https://modelcontextprotocol.io).
9 
10> [!IMPORTANT]
11> Ensure that you have read and understood the [Telegram API Terms of Service](https://core.telegram.org/api/terms) before using this server.
12> Any misuse of the Telegram API may result in the suspension of your account.
13 
14## Table of Contents
15- [What is MCP?](#what-is-mcp)
16- [What does this server do?](#what-does-this-server-do)
17  - [Capabilities](#capabilities)
18  - [Prompt examples](#prompt-examples)
19    - [Message Management](#message-management)
20    - [Organization](#organization)
21    - [Communication](#communication)
22- [Installation](#installation)
23  - [Homebrew](#homebrew)
24  - [NPX](#npx)
25  - [From Releases](#from-releases)
26    - [MacOS](#macos)
27    - [Linux](#linux)
28    - [Windows](#windows)
29  - [From Source](#from-source)
30- [Configuration](#configuration)
31  - [Authorization](#authorization)
32  - [Client Configuration](#client-configuration)
33- [Star History](#star-history)
34 
35## What is MCP?
36 
37The 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.
38 
39## What does this server do?
40 
41### Capabilities
42 
43- [x] Get current account information (`tool: tg_me`)
44- [x] List dialogs with optional unread filter (`tool: tg_dialogs`)
45- [x] Mark dialog as read (`tool: tg_read`)
46- [x] Retrieve messages from specific dialog (`tool: tg_dialog`)
47- [x] Send draft messages to any dialog (`tool: tg_send`)
48 
49### Prompt examples
50 
51Here are some example prompts you can use with AI assistants:
52 
53#### Message Management
54- "Check for any unread important messages in my Telegram"
55- "Summarize all my unread Telegram messages"
56- "Read and analyze my unread messages, prepare draft responses where needed"
57- "Check non-critical unread messages and give me a brief overview"
58 
59#### Organization
60- "Analyze my Telegram dialogs and suggest a folder structure"
61- "Help me categorize my Telegram chats by importance"
62- "Find all work-related conversations and suggest how to organize them"
63 
64#### Communication
65- "Monitor specific chat for updates about [topic]"
66- "Draft a polite response to the last message in [chat]"
67- "Check if there are any unanswered questions in my chats"
68 
69## Installation
70 
71### Homebrew
72 
73You can install a binary release on macOS/Linux using brew:
74 
75```bash
76# Install
77brew install chaindead/tap/telegram-mcp
78 
79# Update
80brew upgrade chaindead/tap/telegram-mcp
81```
82 
83### NPX
84 
85You can run the latest version directly using npx (supports macOS, Linux, and Windows):
86 
87```bash
88npx -y @chaindead/telegram-mcp
89```
90 
91When using NPX, modify the standard commands and configuration as follows:
92 
93- [Authentication command](#authorization) becomes:
94```bash
95npx -y @chaindead/telegram-mcp auth ...
96```
97 
98- [Claude MCP server configuration](#client-configuration) becomes:
99```json
100{
101  "mcpServers": {
102    "telegram": {
103      "command": "npx",
104      "args": ["-y", "@chaindead/telegram-mcp"],
105      "env": {
106        "TG_APP_ID": "<your-api-id>",
107        "TG_API_HASH": "<your-api-hash>"
108      }
109    }
110  }
111}
112```
113 
114For complete setup instructions, see [Authorization](#authorization) and [Client Configuration](#client-configuration).
115 
116### From Releases
117 
118#### MacOS
119 
120<details>
121 
122> **Note:** The commands below install to `/usr/local/bin`. To install elsewhere, replace `/usr/local/bin` with your preferred directory in your PATH.
123 
124First, download the archive for your architecture:
125 
126```bash
127# For Intel Mac (x86_64)
128curl -L -o telegram-mcp.tar.gz https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Darwin_x86_64.tar.gz
129 
130# For Apple Silicon (M1/M2)
131curl -L -o telegram-mcp.tar.gz https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Darwin_arm64.tar.gz
132```
133 
134Then install the binary:
135 
136```bash
137# Extract the binary
138sudo tar xzf telegram-mcp.tar.gz -C /usr/local/bin
139 
140# Make it executable
141sudo chmod +x /usr/local/bin/telegram-mcp
142 
143# Clean up
144rm telegram-mcp.tar.gz
145```
146</details>
147 
148#### Linux
149<details>
150 
151> **Note:** The commands below install to `/usr/local/bin`. To install elsewhere, replace `/usr/local/bin` with your preferred directory in your PATH.
152 
153First, download the archive for your architecture:
154 
155```bash
156# For x86_64 (64-bit)
157curl -L -o telegram-mcp.tar.gz https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Linux_x86_64.tar.gz
158 
159# For ARM64
160curl -L -o telegram-mcp.tar.gz https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Linux_arm64.tar.gz
161```
162 
163Then install the binary:
164 
165```bash
166# Extract the binary
167sudo tar xzf telegram-mcp.tar.gz -C /usr/local/bin
168 
169# Make it executable
170sudo chmod +x /usr/local/bin/telegram-mcp
171 
172# Clean up
173rm telegram-mcp.tar.gz
174```
175</details>
176 
177#### Windows
178 
179<details>
180 
181#### Windows
1821. Download the latest release for your architecture:
183   - [Windows x64](https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Windows_x86_64.zip)
184   - [Windows ARM64](https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Windows_arm64.zip)
1852. Extract the `.zip` file
1863. Add the extracted directory to your PATH or move `telegram-mcp.exe` to a directory in your PATH
187</details>
188 
189### From Source
190 
191Requirements:
192- Go 1.24 or later
193- GOBIN in PATH
194 
195```bash
196go install github.com/chaindead/telegram-mcp@latest
197```
198 
199## Configuration
200 
201### Authorization
202 
203Before you can use the server, you need to connect to the Telegram API.
204 
2051. Get the API ID and hash from [Telegram API](https://my.telegram.org/auth)
2062. Run the following command:
207   > __Note:__
208   > If you have 2FA enabled: add --password <2fa_password>
209 
210   >  __Note:__
211   > If you want to override existing session: add --new
212 
213   ```bash
214   telegram-mcp auth --app-id <your-api-id> --api-hash <your-api-hash> --phone <your-phone-number>
215   ```
216 
217   📩 Enter the code you received from Telegram to connect to the API.
218 
2193. Done! Please give this project a ⭐️ to support its development.
220 
221### Client Configuration
222 
223Example of Configuring Claude Desktop to recognize the Telegram MCP server.
224 
2251. Open the Claude Desktop configuration file:
226    - in MacOS, the configuration file is located at `~/Library/Application Support/Claude/claude_desktop_config.json`
227    - in Windows, the configuration file is located at `%APPDATA%\Claude\claude_desktop_config.json`
228 
229   > __Note:__
230   > You can also find claude_desktop_config.json inside the settings of Claude Desktop app
231 
2322. Add the server configuration
233   
234   for Claude desktop:
235   ```json
236    {
237      "mcpServers": {
238        "telegram": {
239          "command": "telegram-mcp",
240          "env": {
241            "TG_APP_ID": "<your-app-id>",
242            "TG_API_HASH": "<your-api-hash>",
243            "PATH": "<path_to_telegram-mcp_binary_dir>",
244            "HOME": "<path_to_your_home_directory"
245          }
246        }
247      }
248    }
249   ```
250 
251   for Cursor:
252    ```json
253    {
254      "mcpServers": {
255        "telegram-mcp": {
256          "command": "telegram-mcp",
257          "env": {
258            "TG_APP_ID": "<your-app-id>",
259            "TG_API_HASH": "<your-api-hash>"
260          }
261        }
262      }
263    }
264    ```
265 
266## Star History
267 
268<a href="https://www.star-history.com/#chaindead/telegram-mcp&Date">
269 <picture>
270   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=chaindead/telegram-mcp&type=Date&theme=dark" />
271   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=chaindead/telegram-mcp&type=Date" />
272   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=chaindead/telegram-mcp&type=Date" />
273 </picture>
274</a>