Skip to content
Back to search

telegram-mcp

Telegram MCP for managing dialogs, messages, drafts, read statuses, and more.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/chaindead--telegram-mcp/badge.svg)](/listings/chaindead--telegram-mcp)

HTML

<a href="/listings/chaindead--telegram-mcp"><img src="/api/listings/chaindead--telegram-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Homebrew

You can install a binary release on macOS/Linux using brew:

# Install
brew install chaindead/tap/telegram-mcp

# Update
brew upgrade chaindead/tap/telegram-mcp

NPX

You can run the latest version directly using npx (supports macOS, Linux, and Windows):

npx -y @chaindead/telegram-mcp

When using NPX, modify the standard commands and configuration as follows:

- [Authentication command](#authorization) becomes:

npx -y @chaindead/telegram-mcp auth ...

- [Claude MCP server configuration](#client-configuration) becomes:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "@chaindead/telegram-mcp"],
      "env": {
        "TG_APP_ID": "<your-api-id>",
        "TG_API_HASH": "<your-api-hash>"
      }
    }
  }
}

For complete setup instructions, see [Authorization](#authorization) and [Client Configuration](#client-configuration).

From Releases

MacOS

<details>

> **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:

# For Intel Mac (x86_64)
curl -L -o telegram-mcp.tar.gz https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Darwin_x86_64.tar.gz

# For Apple Silicon (M1/M2)
curl -L -o telegram-mcp.tar.gz https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Darwin_arm64.tar.gz

Then install the binary:

# Extract the binary
sudo tar xzf telegram-mcp.tar.gz -C /usr/local/bin

# Make it executable
sudo chmod +x /usr/local/bin/telegram-mcp

# Clean up
rm telegram-mcp.tar.gz

</details>

Linux

<details>

> **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:

# For x86_64 (64-bit)
curl -L -o telegram-mcp.tar.gz https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Linux_x86_64.tar.gz

# For ARM64
curl -L -o telegram-mcp.tar.gz https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Linux_arm64.tar.gz

Then install the binary:

# Extract the binary
sudo tar xzf telegram-mcp.tar.gz -C /usr/local/bin

# Make it executable
sudo chmod +x /usr/local/bin/telegram-mcp

# Clean up
rm telegram-mcp.tar.gz

</details>

Windows

<details>

Windows

1. Download the latest release for your architecture: - [Windows x64](https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Windows_x86_64.zip) - [Windows ARM64](https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Windows_arm64.zip) 2. Extract the `.zip` file 3. Add the extracted directory to your PATH or move `telegram-mcp.exe` to a directory in your PATH </details>

From Source

Requirements: - Go 1.24 or later - GOBIN in PATH

go install github.com/chaindead/telegram-mcp@latest

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 285 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

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

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.