Comprehensive Telegram integration for MCP-compatible clients that provides full access to Telegram functionality, including messaging, chat management, contact management, and group administration via Telethon.

Installation

From Source Code

git clone https://github.com/chigwell/telegram-mcp.git
cd telegram-mcp
uv sync

Docker Build

docker build -t telegram-mcp:latest .

Docker Compose

docker compose up --build

Run Docker

docker run -it --rm \
  -e TELEGRAM_API_ID="YOUR_API_ID" \
  -e TELEGRAM_API_HASH="YOUR_API_HASH" \
  -e TELEGRAM_SESSION_STRING="YOUR_SESSION_STRING" \
  telegram-mcp:latest

Configuration

Claude Desktop / Cursor

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py"
      ]
    }
  }
}

Available Tools

Tool	Description
get_chats	Get paginated list of chats
list_chats	List chats with metadata and filtering
get_chat	Get detailed chat information
send_message	Send a message to a specific chat
get_messages	Get paginated messages from a chat
reply_to_message	Reply to a specific message
edit_message	Edit your own message
delete_message	Delete a message
forward_message	Forward a message between chats
create_group	Create a new group
create_channel	Create a channel or supergroup
get_participants	List all chat participants
promote_admin	Promote a user to admin
ban_user	Ban a user from a chat
list_contacts	List all contacts

Features

• Full chat and group management capabilities
• Comprehensive messaging tools, including editing, forwarding, and replies
• Contact management and user blocking/unblocking
• Admin functions such as promoting/demoting users and managing bans
• Channel and supergroup creation and management
• Inline keyboard interaction and button clicking
• Poll creation and message pinning
• Public chat and message search functionality
• Privacy settings management
• Media file information retrieval

Environment Variables

Required

• TELEGRAM_API_ID - Your Telegram API ID from my.telegram.org/apps
• TELEGRAM_API_HASH - Your Telegram API Hash from my.telegram.org/apps
• TELEGRAM_SESSION_STRING - Session string generated by session_string_generator.py

Optional

• TELEGRAM_SESSION_NAME - Alternative to session string for file-based sessions

Usage Examples

Analyze my chat history and send a response to the group

Get my recent messages from a specific chat

Send a message to my project group

Create a new group with specific users

List all my contacts and find someone

Notes

Requires Python 3.10+. You need to generate API credentials at my.telegram.org/apps and create a session string using the provided generator script. File operations (sending files, downloading media) have been removed due to MCP environment limitations. The server provides input validation, accepting integer IDs, string IDs, or usernames for chat/user parameters.