telegram-mcp AGENTS.md

AGENTS.md

This file describes how AI agents can use telegram-mcp to organize and manage a user's Telegram account. Any AI model or agent framework that discovers this file can use these workflows.

Server Overview

telegram-mcp is an MCP (Model Context Protocol) server that provides 19 tools for reading, writing, and organizing Telegram chats, channels, and groups. It connects via Telethon (user account, not bot API), so it has full access to everything the user can see.

Agent Workflows

1. Auto-organize channels into folders

The primary workflow. Analyze all channel subscriptions and create themed folders.

Steps:

1. Call list_dialogs(filter="channels", limit=200) to get all channels with IDs, names, and unread counts.
2. For each channel, call get_chat_info(chat_id) and get_messages(chat_id, limit=5) in parallel to get metadata and sample recent content.
3. Analyze channel names, descriptions, and message content to infer topics.
4. Group channels into 5-10 thematic folders (e.g., "Coding", "Design", "News", "Personal").
5. Present the plan to the user as a table before making changes.
6. On confirmation, call create_folder(name, chat_ids) for each folder sequentially (parallel calls will cause ID collisions).

Constraints:

• Folder names are limited to 12 characters.
• Telegram allows up to 10 custom folders.
• Create folders one at a time, not in parallel.

2. Identify cleanup candidates

Find channels worth unsubscribing from or archiving.

Steps:

1. Call list_dialogs(filter="channels", limit=200).
2. Flag channels where last_message_date is older than 6 months (inactive/dead).
3. Flag channels with very high unread_count (500+) as potentially abandoned by the user.
4. For flagged channels, call get_messages(chat_id, limit=3) to check if the channel announced it's shutting down or migrating.
5. Present results as a table with channel name, last active date, unread count, and recommendation (archive, mute, or unsubscribe).
6. On confirmation, call archive_chat or mute_chat as requested. Note: there is no leave_chat tool, so the user must unsubscribe manually.