telegram-mcp-server

KO | EN

gitlite — search

#github #reactjs #svg #chatgpt #json #cloud-native #kubernetes #artificial-intelligence #ruby #windows

telegram-mcp-server

(★ 9)

The ultimate secure Model Context Protocol (MCP) server for Telegram. Features AES-256 in-memory session encryption, real-time radar mode, SQLite caching, and native on-the-fly multimodal audio/video parsing for AI agents.

파일 탐색기

ZIP 다운로드

encrypt_setup.py
LICENSE
main.py
README.md
requirements.txt

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

The ultimate Model Context Protocol (MCP) server for Telegram, designed specifically to empower AI Agents (like Claude, Gemini, etc.) with secure, real-time, and multimodal access to your Telegram account.

Unlike other Telegram MCP implementations, this project focuses heavily on **privacy, cross-platform stability, multimodal native support, and performance**.

## Why Choose Us? (Killer Features)

1. **Native Multimodal Audio & Video Parsing**: 
   AI Agents traditionally struggle with raw `.ogg` voice messages or proprietary Telegram video notes. Our server uses a bundled `ffmpeg` binary (via `imageio-ffmpeg`) to intercept and on-the-fly package audio files into standard `.mp4` containers. This allows advanced multimodal neural networks to natively "hear" and "see" the files without relying on unstable third-party APIs like Google Speech Recognition. It is completely cross-platform!
2. **AES-256 Memory Encryption**: 
   Your Telegram API keys and Session strings are extremely sensitive. Most MCPs leave them as plain `.env` files. We built an interactive `encrypt_setup.py` that derives an AES-256 key from a 4-digit PIN using PBKDF2. Your session is decrypted strictly into memory at runtime—no plain text keys ever touch the disk!
3. **Draft Support & Safety Boundaries**:
   AI agents can safely compose replies by utilizing the `save_draft` tool. You can review the draft in your Telegram app before sending it manually. Furthermore, this MCP is hardcoded to completely block access to Private Messages (DMs) and Bots. Only Group and Supergroup chats are accessible, providing an airtight security perimeter.
4. **Radar Mode (Real-Time Waiting)**:
   Say goodbye to API polling loops. Our server uses `asyncio.Event` to halt the AI's execution thread and instantly wake it up the millisecond a new message arrives in a specified chat.
5. **Ultra-Fast SQLite Caching**:
   We parse incoming messages locally in a background process, ensuring that the AI can instantly search the local SQLite database for context without constantly hammering the Telegram API.

---

## Prerequisites

- Python 3.9+ 
- macOS, Linux, or Windows
- A Telegram API ID and Hash (obtainable at [my.telegram.org](https://my.telegram.org))

*(Note for Linux users without a Desktop Environment: the PIN entry system utilizes `tkinter`. If you are running on a headless server, ensure `python3-tk` is installed and an X11/Wayland display is forwarded, or modify the code to use standard `input()`)*

## Installation (Cross-Platform)

1. Clone this repository.
2. Install the required dependencies:
   ```bash
   pip install -r requirements.txt
   ```
3. Copy `.env.example` to `.env` and fill in your Telegram API credentials:
   ```env
   TELEGRAM_API_ID=12345678
   TELEGRAM_API_HASH=your_api_hash_here
   TELEGRAM_SESSION_NAME=master_account
   ```
4. Run the secure setup script to authenticate and encrypt your session:
   ```bash
   python encrypt_setup.py
   ```
   You will be asked to log in to Telegram via your phone number and verification code. After a successful login, a native GUI prompt will ask you to create a **4-digit PIN**. Your session will be encrypted to `config.enc` and you will be prompted to safely delete the `.env` and `.session` files.

## Running the Server

You can plug this server into your preferred MCP client (such as Claude Desktop, Cursor, or Antigravity IDE) by passing your environment's python executable pointing to `main.py`:

```json
{
  "mcpServers": {
    "TelegramMCP": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["/path/to/Telegram-MCP-Release/main.py"]
    }
  }
}
```

Upon launching the MCP server, a small window will appear requesting your 4-digit PIN. Once entered, the server starts serving tools to your AI!

## Available Tools

- `list_my_chats`: List all group chats available to the AI.
- `find_my_chat`: Search for a specific group chat.
- `search_in_my_chats`: Global keyword search spanning the ultra-fast local SQLite cache and the Telegram Cloud.
- `get_chat_messages`: Fetch message history.
- `get_chat_messages_around`: Fetch context above and below a specific message.
- `get_chat_messages_after`: Fetch messages sequentially after a specific message.
- `search_global_public_chats`: Find public Telegram groups.
- `get_chat_info`: Detailed info about a chat.
- `download_message_media`: Downloads photos, documents, and intelligently converts `.ogg` voice notes to `.mp4` for direct AI ingestion.
- `send_message`: Send messages to permitted chats.
- `save_draft`: Save a composed message as a draft for human review.
- `wait_for_new_messages`: Suspends the AI until a new message arrives (Radar Mode).

telegram-mcp-server

오너의 다른 레포

파일 탐색기

# CDN으로 사용하기

Was this content helpful?

Recent Feedback

telegram-mcp-server

오너의 다른 레포

파일 탐색기

# CDN으로 사용하기

Was this content helpful?

Recent Feedback

Download README