🚀 45telega - Production-Ready Telegram MCP Server

A powerful Model Context Protocol (MCP) server for Telegram with 45+ methods, production-ready deployment, and enterprise features.

✨ Features

• 45+ Telegram Methods: Complete API coverage for messages, chats, users, media
• Production Ready: Docker support, health checks, monitoring, logging
• Secure: Non-root container, environment-based config, session encryption
• Scalable: Async architecture, Redis caching, connection pooling
• Easy Install: One-line installation, auto-updates, multiple deployment options

🚀 Quick Start

Platform-Specific Setup

🪟 Windows + WSL + Kiro IDE

📖 Complete Windows Setup Guide →

Comprehensive step-by-step guide for Windows users with WSL and Kiro IDE integration.

🐧 Linux/macOS

One-Line Install

curl -sSL https://raw.githubusercontent.com/sergekostenchuk/45telega/main/install.sh | bash

PyPI Install

pip install 45telega

Docker Install

docker run -d \
  --name 45telega \
  -p 8765:8765 \
  -e TELEGRAM_API_ID=your_api_id \
  -e TELEGRAM_API_HASH=your_api_hash \
  -v $(pwd)/data:/data \
  ghcr.io/sergekostenchuk/45telega:latest

📋 Prerequisites

• Python 3.9+ or Docker
• Telegram API credentials from my.telegram.org
• 512MB RAM minimum
• Linux/macOS/Windows (with WSL)

🔧 Configuration

1. Get Telegram API Credentials

1. Go to my.telegram.org
2. Login with your phone number
3. Create new application
4. Copy api_id and api_hash

2. Configure Environment

Copy .env.example to .env:

cp ~/.config/45telega/.env.example ~/.config/45telega/.env

Edit with your credentials:

TELEGRAM_API_ID=your_api_id_here
TELEGRAM_API_HASH=your_api_hash_here
TELEGRAM_PHONE=+1234567890  # Optional

3. First Authentication

45telega sign-in --phone +1234567890

Enter the code you receive on Telegram.

🎯 Usage

Start MCP Server

# Native
45telega run

# Docker
docker-compose up -d

# With custom port
45telega run --port 9000

Add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "45telega": {
      "type": "stdio",
      "command": "/Users/you/.local/bin/45telega",
      "args": ["run"],
      "env": {
        "TELEGRAM_API_ID": "your_api_id",
        "TELEGRAM_API_HASH": "your_api_hash"
      }
    }
  }
}

Add to Kiro IDE (Windows + WSL)

See the Windows Setup Guide for detailed Kiro IDE integration instructions.

📚 Available Methods

Messages

• SendMessage - Send text messages
• EditMessage - Edit existing messages
• DeleteMessage - Delete messages
• ForwardMessage - Forward messages
• ReplyToMessage - Reply to specific messages
• SendFile - Send files/media

Chats

• GetChats - List all chats
• GetChatInfo - Get chat details
• GetChatMembers - List chat members
• CreateGroup - Create new group
• CreateChannel - Create new channel
• JoinChatByInvite - Join via invite link

Users

• GetMe - Get current user info
• GetUserInfo - Get user details
• GetContacts - List contacts
• AddContact - Add new contact
• BlockUser - Block user
• UnblockUser - Unblock user

Full API Documentation →

🐳 Docker Deployment

docker-compose.yml

version: '3.8'
services:
  45telega:
    image: ghcr.io/sergekostenchuk/45telega:latest
    restart: unless-stopped
    ports:
      - "8765:8765"
    volumes:
      - ./data:/data
      - ./logs:/logs
    env_file:
      - .env

Run with Docker Compose

docker-compose up -d
docker-compose logs -f  # View logs
docker-compose down     # Stop

🔒 Security

• Non-root container: Runs as unprivileged user
• Environment variables: No hardcoded credentials
• Session encryption: Secure session storage
• Rate limiting: Built-in protection
• Health checks: Automatic recovery

📊 Monitoring

Health Check

curl http://localhost:8765/health

Prometheus Metrics

Enable in .env:

PROMETHEUS_ENABLED=true
PROMETHEUS_PORT=9090

Logging

Logs are stored in ./logs/ with rotation:

tail -f logs/45telega.log

🔄 Updates

Auto-update

45telega update

Manual Update

cd ~/.local/share/45telega
git pull
pip install -e . --upgrade

🧪 Development

Setup Development Environment

git clone https://github.com/sergekostenchuk/45telega
cd 45telega
pip install -e .[dev]

Run Tests

pytest tests/
pytest --cov=telega45  # With coverage

Code Quality

black .          # Format code
ruff check .     # Lint
mypy telega45    # Type check

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing)
5. Open Pull Request

📝 License

MIT License - see LICENSE file.

💬 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

🙏 Acknowledgments

• Telethon - Telegram client library
• MCP - Model Context Protocol
• Claude - AI assistant platform

Made with ❤️ by Sergey Kostenchuk