mcp-telegram

MCP-Telegram exposes Telegram control capabilities to MCP clients by running a dedicated mcp-telegram server. It enables AI agents to send and manage messages, search chats, handle drafts, and download media through a structured toolset that integrates with the Model Context Protocol (MCP). After authenticating with Telegram, you connect MCP clients (such as Claude Desktop or Cursor) to this server, using the provided configuration to route commands and responses between the client and Telegram. The server exposes a rich set of tools to interact with chats and messages, enabling automated workflows and agent-assisted Telegram interactions.

To use the tools, start the mcp-telegram server and then configure your MCP client with the server’s command and environment details. The available tools include messaging actions (send_message, edit_message, delete_message, get_messages), search and navigation tools (search_dialogs, message_from_link), draft management (get_draft, set_draft), and media handling (media_download). You can invoke these tools through MCP prompts to perform tasks like sending a message to a chat, editing a previously sent message, looking up a chat by name, or downloading media from a thread. If you need more detail on parameters, you can run mcp-telegram tools from the command line for usage specifics.

Prerequisites:

• Python 3.10 or higher
• uv (via uv project) installed following their official guide

Step-by-step installation:

1. Install uv if you haven’t already (example):

   • On macOS/Linux: curl -sSf https://uv.sh/getuv.sh | sh
   • On Windows, follow the uv installation guide at https://github.com/astral-sh/uv

2. Install the MCP Telegram CLI tool via uv:

   uv tool install mcp-telegram
   

3. Start the server (as shown in the README example):

   mcp-telegram start
   

4. Prepare your MCP client configuration (as described in the README):

   • Set API_ID and API_HASH obtained from my.telegram.org/apps
   • Place the configuration in your MCP client’s config file and point command to mcp-telegram with the start argument

Prerequisites recap:

• Access to a Telegram account and API credentials (API_ID, API_HASH)
• A working Python environment and uv installed
• MCP-compatible client (e.g., Claude Desktop, Cursor) to connect to the server

Tips and caveats:

• API credentials are sensitive; keep API_ID and API_HASH private and avoid sharing.
• Only one instance using the same Telegram session file can avoid database locked errors; if you run multiple instances, ensure separate session files.
• If your MCP client cannot locate the mcp-telegram command, provide the full path to the executable in the config (use which mcp-telegram or where mcp-telegram to determine it).
• You can retrieve detailed parameter information for the available tools by running: mcp-telegram tools
• Environment variables (API_ID, API_HASH) must be provided in the MCP config under env for the mcp-telegram server to utilize Telegram authentication.