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

MCP Servers