⚡ telegram-mcp-cli

Modern Command-Line Interface & Bot Automation Controller for Telegram

📑 Table of Contents

• ✨ Key Features

• 🏗️ Architecture

• 🚀 Quick Start

• 💻 Command Reference

• 🛡️ Safety & Session Protection

• 🧪 Testing

• 📄 License

Related MCP server: HT MCP Server

✨ Key Features

• 🔑 Instant Session Switching (tg-cli auth <path.session>): Pass any existing Telethon .session file directly. Automatically validates SQLite integrity, detects the target server cluster, and aligns settings.

• 🤖 Bot Testing & Automation: Send text payloads, trigger slash commands (e.g. /start), inspect responses, and click inline keyboard buttons.

• 🛡️ Environment Mismatch Shield: Automatically detects whether your session belongs to the Test Server (Sandbox) or Production Server and protects against cross-environment auth revocation.

• 🔒 Process-Level Session Guard: Prevents concurrent duplicate connections (/tmp/telegram-mcp.lock) to eliminate AuthKeyDuplicatedError.

• 📁 Rich Terminal Display: Colorized output, message panels, button trees, and clean tabular diagnostics powered by rich.

• 💬 Real-Time Interactive Chat (tg-cli chat <@bot>): Live terminal chat session with background streaming of incoming messages, inline button triggers (/click), and history scrolling.

• ⚡ Arbitrary MTProto Execution (tg-cli exec): Direct command-line evaluation of Python MTProto snippets with live client injection.

🏗️ Architecture

flowchart TD
    subgraph Terminal ["User / Agent CLI"]
        CLI["tg-cli (argparse + rich)"]
    end

    subgraph Core ["telegram-mcp-cli Engine"]
        Config["Config Manager (.env)"]
        Shield["Environment Mismatch Shield"]
        Lock["Process Lock (/tmp/telegram-mcp.lock)"]
        Controller["TelegramCliClient (Telethon)"]
    end

    subgraph Telegram ["Telegram MTProto Network"]
        TestDC["Telegram Test DC (Sandbox)"]
        ProdDC["Telegram Production DC (Live)"]
    end

    CLI --> Config
    CLI --> Controller
    Controller --> Lock
    Controller --> Shield
    Shield -->|Test Session| TestDC
    Shield -->|Prod Session| ProdDC

🚀 Quick Start

1. Installation

From PyPI (Recommended):

pip install telegram-mcp-cli

From Source:

git clone https://github.com/Telegram-mcp/telegram-mcp-cli.git
cd telegram-mcp-cli
pip install -e .

2. Configure Authentication

To set up or switch active sessions directly:

# Option A: Point to an existing Telethon .session file
tg-cli auth /path/to/my_account.session

# Option B: Run interactive phone / QR login
tg-cli auth login

3. Verify Connection

tg-cli status

💻 Command Reference

🛡️ Safety & Session Protection

• File Locking: tg-cli uses /tmp/telegram-mcp.lock to ensure no two processes use the session concurrently.

• Instant Lock Clearing (tg-cli unlock): If a background MCP server or orphaned process holds the lock, run tg-cli unlock to cleanly terminate it and free the lock.

• Force Takeover (--force): Pass --force to any command (e.g. tg-cli chat @bot --force or tg-cli status --force) to automatically terminate conflicting background processes before connecting.

• Environment Matching: Test Server sessions (DC 2 Sandbox) and Production sessions cannot be cross-connected. The CLI will abort with a clear warning before Telegram revokes the key.

🧪 Testing

Run the automated unit test suite with pytest:

python3 -m pytest tests -v

📄 License

This project is licensed under the MIT License.