Tg MCP

🚀 MCP Telegram Server

A powerful Telegram server implementation that offers Telegram functionality through a clean API, including message search, sending, and chat management capabilities.

Join our Telegram discussion group for support, updates, and community discussions.

🚀 Quick Start

Prerequisites

• Python 3.x
• Telegram API credentials (API ID, API Hash)
• MCP-compatible environment (e.g., Cursor IDE)

Installation

1. Clone the repository and navigate to the project directory:

git clone https://github.com/leshchenko1979/tg_mcp.git
cd tg_mcp

2. Install the dependencies:

pip install -r requirements.txt

3. Create a .env file in the root directory with your Telegram credentials:

API_ID=your_api_id
API_HASH=your_api_hash
PHONE_NUMBER=+123456789

4. Run the setup script to authenticate with Telegram:

python setup_telegram.py

This will create a session file (mcp_telegram_search.session) that stores your Telegram session data.

Cursor Configuration

To use this server with Cursor IDE:

1. Create a mcp.json file in the .cursor directory with the following content:

{
  "mcpServers": {
    "telegram_server": {
      "type": "local",
      "config": {
        "env_file": ".env"
      }
    }
  }
}

2. Start Cursor and connect to the new MCP server.

✨ Features

• Multi-mode message search:
  • Basic text search
  • Advanced search with custom filters
  • Pattern-based search using regular expressions
• Chat management:
  • List available conversations
  • Send messages with optional reply support
  • Generate message links
• Analysis and data:
  • Chat statistics and analysis
  • Chat data export functionality
• Powerful error handling and logging
• Built on the MCP (Model Control Protocol) architecture

💻 Usage Examples

Basic Usage

Calculate message hash

mcp TelegramServer \
    --hash "Hello, World!"

Advanced Usage

Batch process chat records

for message in $(seq 1 100); do
    mcp TelegramServer \
        --send "Message $message"
done

📚 Documentation

Project Structure

Project Directory/
├── setup_telegram.py         # Telegram setup script
├── requirements.txt          # Project dependencies
├── .env                      # Environment variables (create this file)
├── logs/                    # Log file directory
├── LICENSE                 # MIT License
└── src/
    ├── server.py            # Main server logic
    └── utils.py           # Helper functions and tools

Note: *.session and *.session-journal files will be generated after authentication.

Dependencies

The project depends on the following main packages:

loguru          # Logging
aiohttp         # Asynchronous HTTP
mcp[cli]        # Model Control Protocol
telethon>=1.34.0  # Telegram client
python-dotenv>=1.0.0  # Environment management

📄 License

This project is released under the MIT License. For details, please refer to the LICENSE file.