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.

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

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

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

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

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

.venv/bin/python3 telegram_mcp_server.py

Scan the QR code with your Telegram app (Settings > Devices > Link Desktop Device). This creates a `te