telegram-mcp-light

Lightweight, read-only Telegram MCP server via MTProto. Designed for Claude Desktop.

A focused alternative to existing Telegram MCP servers — better forum topic support, unread digests, history export, and fast response times.

Features

• Read-only + mark-as-read — no sending, editing, or deleting messages
• Forum topic support — list topics, read messages per topic, topic-scoped search
• Unread digest — aggregated unread messages across chats, topics, and folders
• History export — export to JSON, CSV, or TXT for any date range
• 8 tools — minimal footprint, one request = one result

Tools

Tool	Description
get_unread_chats	List chats with unread messages, filter by type/folder/muted
list_folders	List Telegram folders with their chats and unread counts
list_topics	List topics in a forum supergroup with unread counts
get_messages	Read messages from a chat or specific forum topic
mark_as_read	Mark a chat or topic as read
search_history	Full-text search in a chat or topic (supports topic-scoped search)
get_digest	Aggregated unread digest across multiple sources
export_messages	Export message history to JSON, CSV, or TXT

Prerequisites

• Python 3.10+
• Telegram API credentials (API_ID and API_HASH from my.telegram.org)

Installation

From PyPI:

pip install telegram-mcp-light

Via uvx (no install):

uvx telegram-mcp-light

From source:

git clone https://github.com/numados/telegram-mcp-light.git
cd telegram-mcp-light
pip install .

Setup

1. Get Telegram API Credentials

1. Go to my.telegram.org/apps
2. Log in with your phone number (international format, e.g. +1234567890)
3. Under API development tools, create a new application:
   • App title and Short name — anything you like, these don't matter
   • Platform — can be left as default
4. After creation, copy your api_id (a number) and api_hash (a hex string)

2. Generate a Session

The server needs a Telethon session to authenticate with Telegram. Two options are available:

Option A: Session String (recommended)

A session string is a single base64-encoded token you can pass via environment variable — no files needed.

export API_ID=your_api_id
export API_HASH=your_api_hash
python auth.py

The script will:

1. Ask for your phone number (international format, e.g. +1234567890)
2. Send a verification code to your Telegram app
3. Ask you to enter the code
4. Print SESSION_STRING=... — copy and save it securely

Set the string in your environment:

export SESSION_STRING=your_session_string_here

Option B: File-based Session

export API_ID=your_api_id
export API_HASH=your_api_hash
python auth.py --file

This saves the session to ~/.config/telegram-mcp-light/session.session. You can override the path with the SESSION_FILE environment variable.

Do NOT copy an existing .session file from another Telegram client. Copying duplicates the auth key and causes AuthKeyDuplicatedError when both clients run concurrently. Always generate a fresh session.

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": ["telegram-mcp-light"],
      "env": {
        "API_ID": "your_api_id",
        "API_HASH": "your_api_hash",
        "SESSION_STRING": "your_session_string"
      }
    }
  }
}

Or if installed from source:

{
  "mcpServers": {
    "telegram": {
      "command": "python",
      "args": ["/path/to/telegram-mcp-light/server.py"],
      "env": {
        "API_ID": "your_api_id",
        "API_HASH": "your_api_hash",
        "SESSION_STRING": "your_session_string"
      }
    }
  }
}

Known Limitations

• General topic (id=1): The General topic in forum groups cannot be isolated via topic_id=1. It falls back to whole-chat scope.
• Word-based search: Telegram's server-side search matches whole words, not substrings. Searching "error" won't match "ValueError".
• No media: This server handles text messages only — no file/photo downloads.
• Export directory: Exports are restricted to ~/telegram-mcp-exports/ for security.

Troubleshooting

AuthKeyDuplicatedError You copied a .session file instead of creating a fresh one. Delete the copied file and run python auth.py again.

Session not authorized The session file doesn't exist or expired. Run python auth.py to create/refresh it.

RuntimeError: API_ID not set Set API_ID and API_HASH environment variables, or create a .env file (copy from .env.example).

Rate limiting (FloodWaitError) Telegram rate-limits API calls. The server handles short waits automatically. For long waits (>60s), the tool returns an error — wait and retry.

Chat is not a forum group list_topics only works on supergroups with forum mode enabled. Use get_messages for regular groups.

License

MIT — see LICENSE.