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

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