telegram-mcp

Telegram MCP server that gives AI agents full access to your chats, channels, and groups. Works with any MCP-compatible client (Claude Code, Cursor, etc.). Built with Telethon.

Read messages, send replies, and organize your Telegram: auto-categorize channels into folders, mute noisy chats, archive stale ones, and clean up subscriptions. See AGENTS.md for ready-to-use workflows.

What can it do?

Read - list chats/channels/groups, fetch and search messages, get chat details

Write - send, edit, delete, and forward messages, pin/unpin, mark as read

Organize - archive/unarchive, mute/unmute, create and manage chat folders

AI Workflows

The tools are designed to work together for multi-step organization tasks. AGENTS.md includes ready-to-use workflows:

• Auto-organize channels into folders - fetch all channels, sample recent messages to infer topics, group into themed folders
• Identify cleanup candidates - find inactive or high-unread channels, suggest archive/mute/unsubscribe
• Triage unread messages - summarize what's important across chats, bulk mark-read the rest
• Reorganize existing folders - audit folder structure, find uncategorized chats, restructure

Setup

1. Get Telegram API credentials

Go to my.telegram.org/apps and create an application. You'll get an API_ID and API_HASH.

2. Install

git clone https://github.com/VovaVindar/telegram-mcp.git
cd telegram-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

3. Configure

cp .env.example .env
# Edit .env with your API_ID and API_HASH

4. Authenticate

.venv/bin/python3 telegram_mcp_server.py

Scan the QR code with your Telegram app (Settings > Devices > Link Desktop Device). This creates a telegram.session file that stores your auth state.

5. Connect to Claude Code

The .mcp.json file registers the server automatically. Just open Claude Code in this directory and the tools will be available.

To use it from any directory, add this to your ~/.claude/claude_code_config.json:

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "/absolute/path/to/telegram-mcp/.venv/bin/fastmcp",
      "args": ["run", "/absolute/path/to/telegram-mcp/telegram_mcp_server.py"]
    }
  }
}

Available Tools

Tool	Description
list_dialogs	List chats/channels/groups with optional filter
get_messages	Fetch messages (use "me" for Saved Messages)
search_messages	Search messages by text, optionally within a chat
get_chat_info	Get details about a chat or user
send_message	Send a message (supports reply)
edit_message	Edit an existing message
delete_messages	Delete messages by ID
forward_messages	Forward messages between chats
archive_chat	Archive a chat
unarchive_chat	Unarchive a chat
pin_message	Pin a message in a chat
unpin_message	Unpin a message
mark_read	Mark all messages in a chat as read
mute_chat	Mute a chat (optionally for N hours)
unmute_chat	Unmute a chat
list_folders	List all chat folders
create_folder	Create a new folder with specified chats
update_folder	Rename or modify folder chats
delete_folder	Delete a folder

Tips

• Use chat_id="me" to target Saved Messages
• Paginate with offset_id: pass the last message ID from the previous batch
• Folder names are limited to 12 characters by Telegram

License

MIT