Labsco
MCP SERVER

Telegram MCP Server

by chigwell ↗

Run your own Telegram account from an agent — read and search chats, send and schedule messages, manage groups and contacts, and wait for a reply to arrive.

Team Chat Platforms
Summary
An agent that can hold a Telegram conversation, including the waiting.

Aliases let you name a person the way you actually say it while only an exact saved wording ever sends, so a near-miss asks instead of messaging the wrong contact. The wait tools then let the agent stop, receive the reply, and continue rather than polling or giving up.

What it is

A Telegram integration built on Telethon that exposes account, chat, message, contact, media, folder and admin operations over MCP. It signs in as your user account, not as a bot.

What you get
  • Chats and groups: list chats, inspect metadata, create groups and channels, join and leave, invite users, manage admins, bans, default permissions, slow mode, topics, invite links and read receipts
  • Messages: send, schedule, edit, delete, forward, pin, search, inspect context, create polls, manage reactions and press inline callback buttons. `send_message`, `reply_to_message` and `edit_message` also take server-side rich formatting with tables, headings and collapsible sections, which requires Telegram Premium and returns a structured `telegram_premium_required` result rather than sending anything when the account lacks it
  • Remembered contacts: `set_contact_alias` teaches it what you call someone, and every tool taking a `chat_id` understands that name afterwards. Only an exact saved wording ever sends — similar wording is matched only to suggest, and confirming saves it as its own alias
  • `list_contact_aliases`, `delete_contact_alias` and a save path that refuses any target it would have to guess at
  • Media: send files, download media, upload files, send voice notes, stickers and GIFs, and inspect message media
  • Waiting for replies: `wait_for_new_message` and `wait_for_settled_message`, optionally scoped to one chat, or an opt-in event feed via `enable_incoming_feed` / `incoming_feed_status` / `disable_incoming_feed` for clients that can wake an agent on external output
  • Multiple accounts through suffixed session variables, where read-only tools fan out across all accounts and write tools require you to name one
Requirements

Python 3.10+, Telegram API credentials from my.telegram.org/apps, and a session string. Do not install it from PyPI: the `telegram-mcp` name there belongs to a different project, and passing your API credentials to that package exposes your Telegram account to unrelated third-party code. Clone the repository, run `uv sync`, then `uv run session_string_generator.py` — with `--qr` when you can scan from another device or `--phone` for code login — and set `TELEGRAM_API_ID`, `TELEGRAM_API_HASH` and `TELEGRAM_SESSION_STRING`. `TELEGRAM_EXPOSED_TOOLS=read-only` registers only read-only tools, and `read-only+send_message,reply_to_message` adds named write tools back; an unknown name aborts startup rather than silently narrowing the surface. `MCP_TRANSPORT` selects stdio, http or sse, with HTTP binding 127.0.0.1:8765 and serving `/mcp`. File-path tools stay disabled until allowed roots are configured, either from the client's MCP Roots or as arguments after `main.py`. A session string grants access to the account it belongs to.

Setup effort

One command plus a key — pip install "git+https://github.com/chigwell/telegram-mcp.git@<tag-or-commit>", then supply credentials