piat0n/telegram-mcp-server

This project is a Model Context Protocol server that gives AI agents like Claude or Gemini secure, real time access to a Telegram account. It is built specifically for privacy, cross platform stability, and handling audio and video content, distinguishing it from other Telegram MCP projects the author has seen. One notable feature is native handling of audio and video messages. Telegram voice notes and video messages come in formats AI models cannot easily process, so the server uses a bundled ffmpeg tool to convert them into standard mp4 files on the fly, letting multimodal AI models listen to and watch these files directly rather than relying on separate transcription services. Telegram API keys and session data are also encrypted in memory using AES-256, derived from a four digit PIN you set during setup, so plain text credentials never sit on disk. The server refuses to access private direct messages or bot conversations, only allowing group and supergroup chats, and it supports saving AI composed replies as drafts for a human to review before sending. A radar mode lets the AI wait efficiently for a new message rather than repeatedly polling, and incoming messages are cached locally in SQLite so searches do not need to hit Telegram's servers every time. To set it up, you need Python 3.9 or later on macOS, Linux, or Windows, plus a Telegram API ID and hash obtained from Telegram's own developer site. After cloning the repository and installing the Python dependencies, you copy an example environment file, fill in your Telegram credentials, and run a setup script that logs you into Telegram and asks you to create a four digit PIN to encrypt your session. Linux users without a desktop environment need the tkinter library and a display available for that PIN entry window, or they can modify the code to use a plain text prompt instead. Once set up, the server can be added to an MCP client such as Claude Desktop or Cursor by pointing it at the project's main Python file, and launching it will prompt for your PIN before it starts serving tools. Those tools include listing and searching your chats, fetching message history around a specific point, downloading and converting media files, sending messages, saving drafts, and waiting for new messages to arrive.