Skip to content
Back to search

mcp-telegram

MCP server to work with Telegram through MTProto

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/sparfenyuk--mcp-telegram/badge.svg)](/listings/sparfenyuk--mcp-telegram)

HTML

<a href="/listings/sparfenyuk--mcp-telegram"><img src="/api/listings/sparfenyuk--mcp-telegram/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.

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.

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 · 209 lines

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

  1. # Telegram MCP server
  2. - [Telegram MCP server](#telegram-mcp-server)
  3. - [About](#about)
  4. - [What is MCP?](#what-is-mcp)
  5. - [What does this server do?](#what-does-this-server-do)
  6. - [Practical use cases](#practical-use-cases)
  7. - [Prerequisites](#prerequisites)
  8. - [Installation](#installation)
  9. - [Configuration](#configuration)
  10. - [Telegram API Configuration](#telegram-api-configuration)
  11. - [Claude Desktop Configuration](#claude-desktop-configuration)
  12. - [Telegram Configuration](#telegram-configuration)
  13. - [Development](#development)
  14. - [Getting started](#getting-started)
  15. - [Debugging the server in terminal](#debugging-the-server-in-terminal)
  16. - [Debugging the server in the Inspector](#debugging-the-server-in-the-inspector)
  17. - [Troubleshooting](#troubleshooting)
  18. - [Message 'Could not connect to MCP server mcp-telegram'](#message-could-not-connect-to-mcp-server-mcp-telegram)
  19. ## About
  20. The server is a bridge between the Telegram API and the AI assistants and is based on the [Model Context Protocol](https://modelcontextprotocol.io).
  21. > [!IMPORTANT]
  22. > Ensure that you have read and understood the [Telegram API Terms of Service](https://core.telegram.org/api/terms) before using this server.
  23. > Any misuse of the Telegram API may result in the suspension of your account.
  24. <a href="https://glama.ai/mcp/servers/484jega1au">
  25. <img width="380" height="200" src="https://glama.ai/mcp/servers/484jega1au/badge" alt="Telegram Server MCP server" />
  26. </a>
  27. ## What is MCP?
  28. 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.
  29. ## What does this server do?
  30. As of not, the server provides read-only access to the Telegram API.
  31. - [x] Get the list of dialogs (chats, channels, groups)
  32. - [x] Get the list of (unread) messages in the given dialog
  33. - [ ] Mark chanel as read
  34. - [ ] Retrieve messages by date and time
  35. - [ ] Download media files
  36. - [ ] Get the list of contacts
  37. - [ ] Draft a message
  38. - ...
  39. ## Practical use cases
  40. - [x] Create a summary of the unread messages
  41. - [ ] Find contacts with upcoming birthdays and schedule a greeting
  42. - [ ] Find discussions on a given topic, summarize them and provide a list of links
  43. ## Prerequisites
  44. - [`uv` tool](https://docs.astral.sh/uv/getting-started/installation/)
  45. ## Installation
  46. ```bash
  47. uv tool install git+https://github.com/sparfenyuk/mcp-telegram
  48. ```
  49. > [!NOTE]
  50. > If you have already installed the server, you can update it using `uv tool upgrade --reinstall` command.
  51. > [!NOTE]
  52. > If you want to delete the server, use the `uv tool uninstall mcp-telegram` command.
  53. ## Configuration
  54. ### Telegram API Configuration
  55. Before you can use the server, you need to connect to the Telegram API.
  56. 1. Get the API ID and hash from [Telegram API](https://my.telegram.org/auth)
  57. 2. Run the following command:
  58. ```bash
  59. mcp-telegram sign-in --api-id <your-api-id> --api-hash <your-api-hash> --phone-number <your-phone-number>
  60. ```
  61. Enter the code you received from Telegram to connect to the API.
  62. The password may be required if you have two-factor authentication enabled.
  63. > [!NOTE]
  64. > To log out from the Telegram API, use the `mcp-telegram logout` command.
  65. ### Claude Desktop Configuration
  66. Configure Claude Desktop to recognize the Exa MCP server.
  67. 1. Open the Claude Desktop configuration file:
  68. - in MacOS, the configuration file is located at `~/Library/Application Support/Claude/claude_desktop_config.json`
  69. - in Windows, the configuration file is located at `%APPDATA%\Claude\claude_desktop_config.json`
  70. > __Note:__
  71. > You can also find claude_desktop_config.json inside the settings of Claude Desktop app
  72. 2. Add the server configuration
  73. ```json
  74. {
  75. "mcpServers": {
  76. "mcp-telegram": {
  77. "command": "mcp-server",
  78. "env": {
  79. "TELEGRAM_API_ID": "<your-api-id>",
  80. "TELEGRAM_API_HASH": "<your-api-hash>",
  81. },
  82. }
  83. }
  84. }
  85. }
  86. ```
  87. ### Telegram Configuration
  88. Before working with Telegram’s API, you need to get your own API ID and hash:
  89. 1. Login to your Telegram account with the phone number of the developer account to use.
  90. 1. Click under API Development tools.
  91. 1. 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.
  92. 1. 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!__
  93. ## Development
  94. ### Getting started
  95. 1. Clone the repository
  96. 2. Install the dependencies
  97. ```bash
  98. uv sync
  99. ```
  100. 3. Run the server
  101. ```bash
  102. uv run mcp-telegram --help
  103. ```
  104. Tools can be added to the `src/mcp_telegram/tools.py` file.
  105. How to add a new tool:
  106. 1. Create a new class that inherits from ToolArgs
  107. ```python
  108. class NewTool(ToolArgs):
  109. """Description of the new tool."""
  110. pass
  111. ```
  112. Attributes of the class will be used as arguments for the tool.
  113. The class docstring will be used as the tool description.
  114. 2. Implement the tool_runner function for the new class
  115. ```python
  116. @tool_runner.register
  117. async def new_tool(args: NewTool) -> t.Sequence[TextContent | ImageContent | EmbeddedResource]:
  118. pass
  119. ```
  120. The function should return a sequence of TextContent, ImageContent or EmbeddedResource.
  121. The function should be async and accept a single argument of the new class.
  122. 3. Done! Restart the client and the new tool should be available.
  123. Validation can accomplished either through Claude Desktop or by running the tool directly.
  124. ### Debugging the server in terminal
  125. To run the tool directly, use the following command:
  126. ```bash
  127. # List all available tools
  128. uv run cli.py list-tools
  129. # Run the concrete tool
  130. uv run cli.py call-tool --name ListDialogs --arguments '{"unread": true}'
  131. ```
  132. ### Debugging the server in the Inspector
  133. The MCP inspector is a tool that helps to debug the server using fancy UI. To run it, use the following command:
  134. ```bash
  135. npx @modelcontextprotocol/inspector uv run mcp-telegram
  136. ```
  137. > [!WARNING]
  138. > Do not forget to define Environment Variables TELEGRAM_API_ID and TELEGRAM_API_HASH in the inspector.
  139. ## Troubleshooting
  140. ### Message 'Could not connect to MCP server mcp-telegram'
  141. If you see the message 'Could not connect to MCP server mcp-telegram' in Claude Desktop, it means that the server configuration is incorrect.
  142. Try the following:
  143. - Use the full path to the `uv` binary in the configuration file
  144. - Check the path to the cloned repository in the configuration file

Ratings and comments

Sign in to rate this skill.

Sign in

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