telegram-read-mcp

A minimal read-only MCP server that exposes Telegram chat and forum-topic reading via Streamable HTTP. It uses Telethon user sessions to authenticate with Telegram's API and FastMCP to serve tools over the Model Context Protocol. The server is intentionally read-only — it never sends messages or modifies any Telegram data.

Prerequisites

• Python 3.12+
• uv installed locally
• Telegram API credentials from https://my.telegram.org (API ID and API hash)

Installation

git clone <repo>
cd telegram-read-mcp
uv sync

First Login

Telegram requires an authenticated user session before the server can read any data.

1. Copy .env.example to .env and fill in your credentials:

   cp .env.example .env
   # edit .env and set TG_API_ID and TG_API_HASH
   chmod 600 .env

2. Run the login script:

   uv run python scripts/first-login.py

3. Choose a login method:

   • QR code (recommended): The script displays a QR code in your terminal. On your phone, go to Telegram > Settings > Devices > Link Desktop Device and scan it. This is the most reliable method.
   • Phone number + code: Enter your phone number (with country code, e.g. +34...). Telegram sends a code to your Telegram app (check the "Telegram" service chat). If you have 2FA enabled, you'll also be prompted for your cloud password.

4. A session file is saved to disk and reused on every subsequent server start. You do not need to log in again unless the session expires or the file is deleted. Restrict it to the current user:

   chmod 600 telegram_read_mcp.session*

Running the Server

HTTP mode (default):

scripts/run-http.sh
# or
uv run telegram-read-mcp

Stdio mode (for MCP clients that speak stdio):

scripts/run-stdio.sh
# or
uv run python -m telegram_read_mcp.server --stdio

The HTTP server listens at http://127.0.0.1:8765/mcp by default. The host and port are configurable via environment variables (see Configuration).

MCP Tools Reference

Tool	Parameters	Description
list_chats	include_archived=false, limit=200, query=null	List joined groups and supergroups
get_chat	chat_id	Get metadata for one chat (includes is_forum flag)
list_topics	chat_id, limit=100, query=null	List forum topics (returns is_forum=false for non-forum chats)
get_messages	chat_id, limit=50, before_message_id=null, allow_forum_root=false	Read messages from a regular group (rejects forum chats by default)
get_topic_messages	chat_id, topic_id, limit=50, before_message_id=null	Read messages from a specific forum topic
search_messages	chat_id, query, limit=50	Server-side full-text search within a chat
search_topic_messages	chat_id, topic_id, query, limit=50	Search within a specific forum topic (client-side filtered)

Topic Semantics

Understanding how Telegram forum topics map to the API is important for using the topic-related tools correctly.

Forums are supergroups with threads, not separate chats. A Telegram forum supergroup is a single chat entity. Topics are threads that live inside it — they are not independent chats and do not have their own chat IDs.

topic_id comes from list_topics. Call list_topics with the forum's chat_id to discover available topics and their IDs. The topic_id values correspond to Telegram's internal forum topic identifiers.

Message retrieval uses thread/reply semantics. Fetching messages for a topic uses Telethon's reply_to parameter, which maps to Telegram's GetRepliesRequest under the hood. This retrieves messages that are part of a specific thread.

The General topic (topic_id=1) is a special case. The reply_to API may not work for the General topic (the default topic that exists in every forum). When topic_id=1 is requested, the server falls back to filtering messages by reply_to_top_id instead.

Safety scan cap. For the General topic fallback path and for search_topic_messages (which performs client-side filtering), the server scans at most 5000 messages to prevent hanging indefinitely on large chats. Results may be incomplete if there are more than 5000 messages in scope.

Service messages and edge cases. Forum topics may contain service messages (topic creation, title changes, etc.) that appear alongside normal messages. Some edge cases exist around pinned messages and topic-level events.

get_messages rejects forum supergroups by default. Calling get_messages on a forum chat returns an error to prevent accidentally reading the unstructured root stream. Pass allow_forum_root=true to override this and read messages from the forum root anyway.

Error Codes

Code	Meaning
CHAT_NOT_FOUND	Chat ID not found or not accessible with the current session
NOT_A_FORUM	The chat exists but is not a forum-enabled supergroup
TOPIC_NOT_FOUND	Topic ID not found in the specified forum
INVALID_LIMIT	Limit is out of range — must be between 1 and 200
TELEGRAM_ERROR	An error was returned by the Telegram API
TELEGRAM_AUTH_REQUIRED	The session is not authorized — run first-login.py
FORUM_ROOT_REJECTED	Tried to read a forum chat with get_messages without setting allow_forum_root=true

Configuration

All configuration is via environment variables, typically stored in .env.

Variable	Required	Default	Description
TG_API_ID	Yes	—	Telegram API ID from my.telegram.org
TG_API_HASH	Yes	—	Telegram API hash from my.telegram.org
TG_SESSION_PATH	No	telegram_read_mcp	Path to the session file, without the .session extension
MCP_HOST	No	127.0.0.1	Address the HTTP server binds to
MCP_PORT	No	8765	Port the HTTP server listens on

Systemd Deployment

To run the server as a system service:

1. Create a dedicated system user:

   sudo useradd -r -s /bin/false telegram-mcp

2. Copy only the tracked project files to /opt/telegram-read-mcp:

   sudo mkdir -p /opt/telegram-read-mcp
   git archive --format=tar HEAD | sudo tar -x -C /opt/telegram-read-mcp
   sudo chown -R telegram-mcp:telegram-mcp /opt/telegram-read-mcp

   This avoids copying local-only files such as .env, .venv, .git, and *.session.

3. Sync the project environment:

   cd /opt/telegram-read-mcp
   sudo -u telegram-mcp uv sync --frozen

4. Copy your .env file and run the first login as the service user:

   sudo cp .env /opt/telegram-read-mcp/.env
   sudo chown telegram-mcp:telegram-mcp /opt/telegram-read-mcp/.env
   sudo chmod 600 /opt/telegram-read-mcp/.env
   cd /opt/telegram-read-mcp
   sudo -u telegram-mcp uv run python scripts/first-login.py
   sudo chmod 600 /opt/telegram-read-mcp/*.session*

5. Install the systemd unit:

   sudo cp systemd/telegram-read-mcp.service /etc/systemd/system/
   sudo systemctl daemon-reload

6. Enable and start the service:

   sudo systemctl enable --now telegram-read-mcp

Check status with sudo systemctl status telegram-read-mcp and follow logs with journalctl -u telegram-read-mcp -f.

uv Notes

• uv sync creates and maintains the local .venv for this project.
• uv.lock should be committed so deploys can use uv sync --frozen.
• uvx is not the primary deployment path here. The server uses a project-local environment because it depends on a persistent session file and is intended to run as a long-lived service.