Skip to content
Back to search

mcp-telegram

MCP Server for Telegram

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

HTML

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

Prerequisites

- Python 3.10 or higher - [`uv`](https://github.com/astral-sh/uv) Install via the [official uv guide](https://github.com/astral-sh/uv#installation).

Installation

Install the `mcp-telegram` CLI tool:

uv tool install mcp-telegram

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

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

  1. <div align="center">
  2. <img src="logo.png" alt="MCP Telegram Logo" width="150"/>
  3. <h2 style="margin-top: 0">Enable LLMs to control your Telegram</h2>
  4. </div>
  5. <div align="center">
  6. <a href="https://github.com/dryeab/mcp-telegram/stargazers"><img src="https://img.shields.io/github/stars/dryeab/mcp-telegram?style=social" alt="GitHub stars"></a>
  7. <a href="https://badge.fury.io/py/mcp-telegram"><img src="https://badge.fury.io/py/mcp-telegram.svg" alt="PyPI version"></a>
  8. <a href="https://x.com/dryeab"><img src="https://img.shields.io/twitter/follow/dryeab?style=social" alt="Twitter Follow"></a>
  9. </div>
  10. <h3></h3>
  11. **Connect Large Language Models to Telegram via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction).**
  12. Built with [Telethon](https://github.com/LonamiWebs/Telethon), this server allows AI agents to interact with Telegram, enabling features like sending/editing/deleting messages, searching chats, managing drafts, downloading media, and more using the [MTProto](https://core.telegram.org/mtproto).
  13. ---
  14. <details>
  15. <summary><strong>Table&nbsp;of&nbsp;Contents</strong></summary>
  16. - [🚀 Getting Started](#-getting-started)
  17. - [Prerequisites](#prerequisites)
  18. - [Installation](#installation)
  19. - [⚙️ Usage](#️-usage)
  20. - [Login](#login)
  21. - [Connect to the MCP server](#connect-to-the-mcp-server)
  22. - [🧰 Available Tools](#-available-tools)
  23. - [📨 Messaging Tools](#-messaging-tools)
  24. - [🔍 Search & Navigation](#-search--navigation)
  25. - [📝 Draft Management](#-draft-management)
  26. - [📂 Media Handling](#-media-handling)
  27. - [🛠️ Troubleshooting](#️-troubleshooting)
  28. - [🤝 Contributing](#-contributing)
  29. - [📝 License](#-license)
  30. </details>
  31. ---
  32. ## 🚀 Getting Started
  33. ### Prerequisites
  34. - Python 3.10 or higher
  35. - [`uv`](https://github.com/astral-sh/uv) Install via the [official uv guide](https://github.com/astral-sh/uv#installation).
  36. ### Installation
  37. Install the `mcp-telegram` CLI tool:
  38. ```bash
  39. uv tool install mcp-telegram
  40. ```
  41. ## ⚙️ Usage
  42. > [!IMPORTANT]
  43. > Please ensure you have read and understood Telegram's [ToS](https://telegram.org/tos) before using this tool. Misuse of this tool may result in account restrictions.
  44. The `mcp-telegram` command-line tool is your entry point.
  45. ```bash
  46. mcp-telegram --help # See all commands
  47. ```
  48. ### Login
  49. First, authenticate with your Telegram account:
  50. ```bash
  51. mcp-telegram login
  52. ```
  53. This interactive command will prompt you for:
  54. - **API ID & API Hash:** Obtain these from [my.telegram.org/apps](https://my.telegram.org/apps).
  55. - **Phone Number:** Your Telegram-registered phone number (international format, e.g., `+1234567890`).
  56. - **Verification Code:** Sent to your Telegram account upon first login.
  57. - **2FA Password:** If you have Two-Factor Authentication enabled.
  58. Your credentials are securely stored in the session file for future use.
  59. > [!WARNING]
  60. > Keep your API credentials private and never share them publicly
  61. > [!NOTE]
  62. > Use `mcp-telegram logout` to logout from current session or `mcp-telegram clear-session` to remove all stored session data.
  63. ### Connect to the MCP server
  64. To use MCP Telegram with MCP clients like Claude Desktop or Cursor, you'll need to configure the MCP server. The configuration process varies by client and operating system.
  65. For detailed setup instructions, please refer to:
  66. - [Claude Desktop MCP Setup Guide](https://modelcontextprotocol.io/quickstart/user)
  67. - [Cursor MCP Documentation](https://docs.cursor.com/context/model-context-protocol)
  68. The configuration file should contain:
  69. ```json
  70. {
  71. "mcpServers": {
  72. "mcp-telegram": {
  73. "command": "mcp-telegram" /* Use full path if client can't find the command (e.g. "/usr/local/bin/mcp-telegram"). See IMPORTANT section below for full path instructions. */,
  74. "args": ["start"],
  75. "env": {
  76. "API_ID": "<your_api_id>",
  77. "API_HASH": "<your_api_hash>"
  78. }
  79. }
  80. }
  81. }
  82. ```
  83. > [!Note]
  84. > Configuration paths vary by OS and client. For example:
  85. >
  86. > - macOS: `~/Library/Application Support/Claude/` or `~/.cursor/`
  87. > - Windows: `%APPDATA%\Claude\` or `%APPDATA%\Cursor\`
  88. > [!IMPORTANT]
  89. > If your client cannot execute `mcp-telegram` despite it being accessible in the terminal, try using the full path to the executable. You can find this by running `which mcp-telegram` (macOS/Linux) or `where mcp-telegram` (Windows) in your terminal. Replace the `command` value in the configuration with the full path.
  90. After saving the configuration file, restart your application.
  91. ## 🧰 Available Tools
  92. Here's a comprehensive list of tools you can use to interact with Telegram through MCP:
  93. ### 📨 Messaging Tools
  94. | Tool | Description |
  95. | ---------------- | ------------------------------------------------------------- |
  96. | `send_message` | ✉️ Send text messages or files to any user, group, or channel |
  97. | `edit_message` | ✏️ Modify content of previously sent messages |
  98. | `delete_message` | 🗑️ Remove one or multiple messages |
  99. | `get_messages` | 📜 Retrieve message history with advanced filtering options |
  100. ### 🔍 Search & Navigation
  101. | Tool | Description |
  102. | ------------------- | ------------------------------------------------------- |
  103. | `search_dialogs` | 🔎 Find users, groups, and channels by name or username |
  104. | `message_from_link` | 🔗 Access specific messages using Telegram links |
  105. ### 📝 Draft Management
  106. | Tool | Description |
  107. | ----------- | ------------------------------------------ |
  108. | `get_draft` | 📋 View current message draft for any chat |
  109. | `set_draft` | ✍️ Create or clear message drafts |
  110. ### 📂 Media Handling
  111. | Tool | Description |
  112. | ---------------- | ------------------------------------------------------- |
  113. | `media_download` | 📸 Download photos, videos, and documents from messages |
  114. > [!Note]
  115. > For detailed parameter information and example use cases, run `mcp-telegram tools` in your terminal.
  116. ## 🛠️ Troubleshooting
  117. ### Database Locked Errors
  118. Running multiple `mcp-telegram` instances using the _same session file_ can cause `database is locked` errors due to Telethon's SQLite session storage. Ensure only one instance uses a session file at a time.
  119. <details>
  120. <summary>Force-Stopping Existing Processes</summary>
  121. If you need to stop potentially stuck processes:
  122. - **macOS / Linux:** `pkill -f "mcp-telegram"`
  123. - **Windows:** `taskkill /F /IM mcp-telegram.exe /T` (Check Task Manager for the exact process name)
  124. </details>
  125. ## 🤝 Contributing
  126. We welcome contributions! If you'd like to help improve MCP Telegram, please feel free to submit issues, feature requests, or pull requests. Your feedback and contributions help make this project better for everyone.
  127. ## 📝 License
  128. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  129. ---
  130. <div align="center">
  131. <p>Made with ❤️ by <a href="https://x.com/dryeab">Yeabsira Driba</a></p>
  132. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

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