srckod/tele repository overview

⁠Tele - Telegram Automation Engine

⁠Table of Contents

• Why This Project Exists⁠
• Core Features⁠
• Architecture Overview⁠
• Technology Stack⁠
• Quick Start⁠
• Downloads & Releases⁠
• Configuration⁠
• Running Modes⁠
• REST API⁠
• MCP AI Agent Integration⁠
• Custom Filter DSL⁠
• Background Job Processing⁠
• CI/CD & Deployment⁠
• Docker⁠
• Contributing⁠
• License & Disclaimer⁠

⁠🎯 Why This Project Exists

The Telegram Automation Engine or simply Tele was designed to bridge a critical gap in the Telegram automation ecosystem: the need for an enterprise-grade platform that seamlessly integrates traditional Telegram bot operations with modern AI agent capabilities.

While numerous Telegram tools exist for basic automation, they typically suffer from:

⁠🚀 Core Features

⁠🤖 MCP Integration (Model Context Protocol)

Our standout innovation. The engine exposes its full capabilities through the Model Context Protocol, enabling AI agents to programmatically control Telegram operations — transforming it from a simple automation tool into an AI-powered orchestration platform.

• --mcp: Stdio transport for direct AI agent integration (Claude, GPT, etc.)
• --mcp-http: HTTP transport for web-based AI agent connections
• Normal mode: Traditional Telegram bot + REST API

⁠👥 Multi-Account Orchestration

Manage dozens of Telegram accounts simultaneously with enterprise-grade reliability:

• Automatic failover — when an account gets banned, traffic is redistributed
• Per-account flood protection — configurable thresholds prevent API-level bans
• Database-persisted sessions — sessions survive restarts, no re-authentication needed
• Health monitoring — track ban status, send attempts, and flood flags per phone

⁠🔑 Intelligent Access Hash Management

Telegram's MTProto requires access hashes for efficient peer communication. Our engine:

• Automatically collects and caches access hashes during operations
• Persists hashes to MySQL for reuse across sessions and restarts
• Reduces peer resolution API calls by ~90%
• Eliminates the dreaded PEER_ID_INVALID errors

⁠🎯 Custom Filter DSL

A powerful domain-specific language for precise member targeting:

firstname~A,batch=50
active=false,group=mychannel
lastseen>30d,withusername=true

Supports operators: =, !=, ~ (contains), >, <, >=, <=

⁠📊 Background Job Processing

Long-running operations run asynchronously with full lifecycle management:

• Pluggable queue backends: MySQL, Redis (Upstash-compatible), or In-Memory
• Unique job IDs for tracking and status polling
• Status monitoring: pending → running → completed / failed
• Pagination and filtering — list jobs by status, page through results
• Polymorphic job serialization — each job type carries its own payload schema

⁠🌐 Dual Interface Architecture

• Telegram Bot Interface: Interactive keyboard-based navigation for human operators
• REST API: Swagger-documented endpoints secured with API key authentication
• MCP Interface: AI agent consumable tools

⁠📤 Data Exporting

Export filtered member data with background job support, ready for integration with external analytics tools.

⁠🏗️ Architecture Overview

The project follows a feature-based architecture with clean separation of concerns:

Tele/
├── Features/                 # Business logic by feature
│   ├── Api/                  # REST API controllers
│   ├── BulkAdding/           # Bulk join members to channels
│   ├── BulkSending/          # Bulk message delivery
│   ├── Exporting/            # Member data export
│   ├── Mcp/                  # MCP AI agent integration layer
│   ├── Scraping/             # Channel member scraping
│   ├── TelegramBot/          # Interactive bot (keyboards, states, actions)
│   └── TelegramClient/       # MTProto client wrapper with access hash mgmt
├── Infrastructure/           # Cross-cutting concerns
│   ├── Database/             # EF Core context, DAOs, models
│   ├── Extensions/           # DI service registration
│   ├── Middleware/            # API key authentication
│   └── Queue/                # Job queue (MySQL, Redis, Memory)
└── Shared/                   # Shared models, enums, utilities
    └── Models/               # Config, MemberFilter, FilterCondition

⁠Key Design Decisions

⁠🛠️ Technology Stack

⁠⚡ Quick Start

⁠Prerequisites

• .NET 9.0 SDK⁠
• MySQL Server (or Redis for queue backend)
• Telegram Bot Token (from @BotFather⁠)
• Telegram API Credentials (API ID & Hash from my.telegram.org⁠)

⁠Installation

git clone https://github.com/srckod/tele.git
cd tele
dotnet restore
dotnet build

⁠Configuration

Copy config.yaml.example to config.yaml and fill in your credentials:

ActiveMode: "Test"

Brand:
  BotName: "My Automation Bot"

Test:
  ApiToken: "your_bot_token"
  DBHost: "localhost"
  DBName: "telegram_automation"
  DBUser: "root"
  DBPassword: "your_password"
  AppId: 12345678
  AppHash: "your_app_hash"
  AppPhone: "+1234567890"

# Queue backend: "redis", "mysql", or "memory"
QueueType: "memory"

Admins:
  your_username: 123456789

AutomationAPIKey: "generate-a-secure-api-key"

⁠Running

# Normal mode (Telegram Bot + REST API)
dotnet run

# MCP stdio mode (AI agent integration)
dotnet run -- --mcp

# MCP HTTP mode (web-based AI agents)
dotnet run -- --mcp-http

⁠📥 Downloads & Releases

Pre-built single-file executables are available from the GitHub Releases⁠ page:

⁠Windows

1. Download Tele-win-x64.zip from the latest release
2. Extract the archive to a folder of your choice
3. Copy your config.yaml file next to Tele.exe (same directory)
4. Open a terminal in that folder and run:

   Tele.exe
   

   Copy

⁠Linux / macOS

# Download and extract
wget https://github.com/srcKod/tele/releases/latest/download/Tele-linux-x64.tar.gz
tar -xzf Tele-linux-x64.tar.gz
cd linux-x64

# Copy your config.yaml next to the executable
cp /path/to/your/config.yaml .

# Run
./Tele

⁠⚙️ Configuration

The config.yaml supports extensive configuration:

Dual-environment configuration supports Test and Production blocks, each with independent database, Telegram credentials, and MTProto server settings.

⁠🎮 Running Modes

⁠1. Normal Mode (Default)

dotnet run

Starts the Telegram Bot interface (interactive keyboard navigation) alongside the REST API on port 5000. Swagger UI is available at /swagger.

⁠2. MCP Stdio Mode

dotnet run -- --mcp

Communicates via stdio JSON-RPC. Ideal for direct integration with AI agents like Claude Desktop, Cline, or custom AI orchestration pipelines.

⁠3. MCP HTTP Mode

dotnet run -- --mcp-http

Exposes the MCP endpoint at /mcp over HTTP. Perfect for web-based AI agents (e.g. llama.cpp Web UI), remote MCP clients, and distributed AI pipelines. Swagger UI is also available at /swagger in this mode.

⁠MCP API Key Authentication

The MCP HTTP endpoint uses the same X-API-Key authentication as the REST API. All POST requests to /mcp (tool calls) require a valid API key. GET requests (SSE connection initialization) are allowed without auth.

Provide the API key either via the X-API-Key header or the api_key query parameter.

Cline / VS Code MCP configuration:

{
  "mcpServers": {
    "tele": {
      "url": "http://localhost:4951/mcp",
      "type": "streamableHttp",
      "headers": {
        "X-API-Key": "your-api-key-here"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

If your MCP client does not support custom headers, use the api_key query parameter instead:

{
  "mcpServers": {
    "tele": {
      "url": "http://localhost:4951/mcp?api_key=your-api-key-here",
      "type": "streamableHttp",
      "disabled": false,
      "autoApprove": []
    }
  }
}

Claude Desktop MCP configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "tele": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/Tele", "--mcp"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

For the stdio mode (--mcp), no API key is needed since communication happens via stdin/stdout.

⁠Testing MCP tools via curl:

List available tools:

curl -X POST http://localhost:4951/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Get member count:

curl -X POST http://localhost:4951/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_member_count","arguments":{}}}'

⁠📡 REST API

All endpoints are secured with API key authentication (X-API-Key header) and documented via Swagger at /swagger.

⁠🤖 MCP AI Agent Integration

The engine exposes the same functionality as the REST API through MCP tools, consumable by any MCP-compatible AI agent:

Important: Tool names use snake_case (e.g., get_member_count, list_phones, query_members).

⁠filterDsl cheat sheet for query_members:

Example MCP integration with Claude:

{
  "server_name": "tele",
  "tool_name": "query_members",
  "arguments": {
    "filterDsl": "active=true,group=mychannel,batch=50",
    "pageSize": 20
  }
}

⁠🎯 Custom Filter DSL

A compact, expressive domain-specific language for filtering Telegram members.

⁠Syntax

field=value,field!=value,field~value,batch=N,skip=N

⁠Supported Fields

⁠Operators

⁠Examples

# Find active users named "Ali" in a specific channel, limit to 50
active=true,fn~Ali,group=my_channel,batch=50

# Find inactive members without username, collected recently
active=false,withusername=false,collected>2025-01-01

# Find members not seen in 30+ days
lastseen>30d,batch=200

⁠📋 Background Job Processing

All bulk operations run as background jobs, ensuring the API and bot remain responsive.

⁠Architecture

Client → API/MCP → IJobQueue.EnqueueAsync() → MySQL/Redis/Memory
                                                    ↓
                                          QueueWorker (HostedService)
                                                    ↓
                                        ┌─────────────┼─────────────┐
                                        ↓             ↓             ↓
                                   ScrapeHandler  BulkSend     BulkAdd
                                        ↓             ↓             ↓
                                   IJobQueue.UpdateJobStatus() → MySQL/Redis/Memory

⁠Queue Backends

⁠🔄 CI/CD & Deployment

⁠GitHub Actions Pipeline

The project includes a comprehensive CI/CD pipeline (.github/workflows/ci-cd.yml) that:

• Builds and tests on every push and pull request
• Builds and publishes Docker images to Docker Hub on pushes to main
• Creates GitHub Releases with cross-platform single-file executables when version tags are pushed

⁠Cross-Platform Releases

Pushing a version tag automatically produces standalone executables:

git tag v1.0.0
git push origin v1.0.0

Each executable is self-contained (no .NET runtime required).

⁠🐳 Docker

Pre-built Docker images are available on Docker Hub⁠:

docker pull srckod/tele:1.0

⁠Run with config.yaml (Normal Mode)

Mount your config.yaml file into the container — do not mount the entire /app/ directory (that would overwrite the application files):

docker run -d \
  --name tele \
  -p 4951:4951 \
  -v $(pwd)/config.yaml:/app/config.yaml:ro \
  srckod/tele:1.0

⁠Run with MCP HTTP mode

To run in --mcp-http mode, pass it as a command argument after the image name. You also need to set ASPNETCORE_URLS to control the listening port:

docker run -d \
  --name tele-mcp \
  -p 4951:4951 \
  -e ASPNETCORE_URLS=http://0.0.0.0:4951 \
  -v $(pwd)/config.yaml:/app/config.yaml:ro \
  srckod/tele:1.0 \
  --mcp-http

The --mcp-http argument is appended after the image name (Docker passes it to the ENTRYPOINT). The -e flag sets the environment variable for the port.

⁠Check the logs

docker logs tele -f

⁠Build from source

docker build -t tele .
docker run -d \
  --name tele \
  -p 4951:4951 \
  -v $(pwd)/config.yaml:/app/config.yaml:ro \
  tele

⁠🤝 Contributing

We welcome contributions! Areas of particular interest:

• Additional MCP tools — extend AI agent capabilities
• New Filter DSL operators — enhance member targeting precision
• Additional queue backends — RabbitMQ, Azure Service Bus, etc.
• Performance optimizations — chunk tuning, caching strategies
• Web dashboard — real-time monitoring and control UI
• Test coverage — unit and integration tests

Please open an issue first to discuss your proposed changes.

⁠📄 License & Disclaimer

License: MIT — see LICENSE⁠ for details.

Disclaimer: This tool is designed for educational and legitimate marketing purposes only. Users are responsible for ensuring compliance with applicable laws, regulations, and Telegram's Terms of Service. The authors assume no liability for misuse of this software.