Name: Telegram MCP Server by chigwell
Author: chigwell

LABSCO 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

Build from source — git clone https://github.com/chigwell/telegram-mcp.git

See installation options

USE CASES

Sending a message to someone by the name you use

Teach it the alias once; from then on the name you actually say resolves. Unfamiliar wording returns an instruction to confirm rather than a message to the wrong person.

set_contact_aliassend_messagelist_contact_aliases

Waiting for an answer before continuing

Block on a settled incoming message, scoped to one chat so an unrelated conversation does not wake the agent early.

wait_for_settled_messagewait_for_new_message

Handing an agent read access and nothing else

Set the exposed-tools variable to read-only; write tools are never registered, and a typo in the allowlist stops startup instead of quietly producing a narrower surface that looks like it worked.

Running one server for several clients

Use the HTTP transport so a single long-lived process holds one Telegram connection — Telegram throttles and may flag accounts that open many parallel sessions.

Working across a personal and a work account

Suffixed session variables give each account a label; read-only tools fan out over all of them, and write tools make you name the one you meant.

Reacting to messages as they arrive

Turn on the incoming feed and arm a watch on the file it appends to; every settled burst re-invokes the agent without holding a blocking call open.

enable_incoming_feedincoming_feed_statusdisable_incoming_feed

128 tools

Listed in project code.

`list_accounts`

List all configured Telegram accounts with profile info.

INSTALLATION

Connect your client

You clone this one yourself.

Server setup

TERMINAL

git clone https://github.com/chigwell/telegram-mcp.git
cd telegram-mcp
uv sync

Get your API ID and API hash from https://my.telegram.org/apps, then generate a session string and save it securely (--qr logs in by scanning a QR code; --phone uses a verification code):

TERMINAL

uv run session_string_generator.py --qr

For the shared HTTP server, also copy the example environment file and put the three values in it:

TERMINAL

cp .env.example .env

MCP Clients

Claude Desktop, Cursor

JSON

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "<YOUR_PATH_TO_TELEGRAM_MCP>",
        "run",
        "main.py"
      ],
      "env": {
        "TELEGRAM_API_ID": "<YOUR_TELEGRAM_API_ID>",
        "TELEGRAM_API_HASH": "<YOUR_TELEGRAM_API_HASH>",
        "TELEGRAM_SESSION_STRING": "<YOUR_TELEGRAM_SESSION_STRING>"
      }
    }
  }
}

Any MCP client — pip

Install a pinned release into a virtualenv

Not from PyPI: the telegram-mcp name there belongs to a different project. <YOUR_TAG_COMMIT> is a release tag or commit.

ANY MCP CLIENT — PIP · TERMINAL

python -m venv .venv
. .venv/bin/activate
pip install "git+https://github.com/chigwell/telegram-mcp.git@<YOUR_TAG_COMMIT>"
telegram-mcp-generate-session

Point your client at the installed console script

Use the absolute path of .venv/bin/telegram-mcp, and the session string telegram-mcp-generate-session printed.

ANY MCP CLIENT — PIP · JSON

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "<YOUR_PATH_TO_VENV>/bin/telegram-mcp",
      "env": {
        "TELEGRAM_API_ID": "<YOUR_TELEGRAM_API_ID>",
        "TELEGRAM_API_HASH": "<YOUR_TELEGRAM_API_HASH>",
        "TELEGRAM_SESSION_STRING": "<YOUR_TELEGRAM_SESSION_STRING>"
      }
    }
  }
}

Claude Code — HTTP

From your clone, with TELEGRAM_API_ID, TELEGRAM_API_HASH and TELEGRAM_SESSION_STRING in .env. It listens on 127.0.0.1:8765 and serves /mcp; leave it running.

Start one shared server over streamable HTTP

CLAUDE CODE — HTTP · TERMINAL

cd telegram-mcp
MCP_TRANSPORT=http uv run main.py

CLAUDE CODE — HTTP · TERMINAL

claude mcp add --transport http telegram http://127.0.0.1:8765/mcp

Codex — HTTP

From your clone, with TELEGRAM_API_ID, TELEGRAM_API_HASH and TELEGRAM_SESSION_STRING in .env. It listens on 127.0.0.1:8765 and serves /mcp; leave it running.

Start one shared server over streamable HTTP

CODEX — HTTP · TERMINAL

cd telegram-mcp
MCP_TRANSPORT=http uv run main.py

CODEX — HTTP · TERMINAL

codex mcp add telegram --url http://127.0.0.1:8765/mcp

Any MCP client — stdio bridge

From your clone, with TELEGRAM_API_ID, TELEGRAM_API_HASH and TELEGRAM_SESSION_STRING in .env. It listens on 127.0.0.1:8765 and serves /mcp; leave it running.

Start one shared server over streamable HTTP

ANY MCP CLIENT — STDIO BRIDGE · TERMINAL

cd telegram-mcp
MCP_TRANSPORT=http uv run main.py

Bridge a stdio-only client to it with mcp-remote

ANY MCP CLIENT — STDIO BRIDGE · JSON

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  }
}

Telegram MCP Server by chigwell

An agent that can hold a Telegram conversation, including the waiting.

What it is

What you get

Requirements

Setup effort

Sending a message to someone by the name you use

Waiting for an answer before continuing

Handing an agent read access and nothing else

Running one server for several clients

Working across a personal and a work account

Reacting to messages as they arrive

128 tools

list_accounts

list_contacts

search_contacts

get_contact_ids

get_direct_chat_by_contact

get_contact_chats

get_last_interaction

add_contact

delete_contact

block_user

unblock_user

import_contacts

export_contacts

get_blocked_users

send_contact

set_contact_alias

list_contact_aliases

delete_contact_alias

get_chats

subscribe_public_channel

list_topics

enable_forum_topics

create_forum_topic

list_chats

get_chat

search_public_chats

resolve_username

get_full_chat

mute_chat

unmute_chat

archive_chat

unarchive_chat

get_common_chats

get_message_read_by

get_message_link

get_messages

send_message

send_scheduled_message

get_scheduled_messages

delete_scheduled_message

list_inline_buttons

press_inline_button

list_messages

transcribe_voice

get_message_context

get_send_as

forward_message

forward_messages

edit_message

delete_message

delete_chat_history

delete_messages_bulk

pin_message

unpin_message

unpin_all_messages

mark_as_read

reply_to_message

search_messages

search_global

get_history

get_pinned_messages

create_poll

send_reaction

remove_reaction

get_message_reactions

save_draft

get_drafts

`list_accounts`

`list_contacts`

`search_contacts`

`get_contact_ids`

`get_direct_chat_by_contact`

`get_contact_chats`

`get_last_interaction`

`add_contact`

`delete_contact`

`block_user`

`unblock_user`

`import_contacts`

`export_contacts`

`get_blocked_users`

`send_contact`

`set_contact_alias`

`list_contact_aliases`

`delete_contact_alias`

`get_chats`

`subscribe_public_channel`

`list_topics`

`enable_forum_topics`

`create_forum_topic`

`list_chats`

`get_chat`

`search_public_chats`

`resolve_username`

`get_full_chat`

`mute_chat`

`unmute_chat`

`archive_chat`

`unarchive_chat`

`get_common_chats`

`get_message_read_by`

`get_message_link`

`get_messages`

`send_message`

`send_scheduled_message`

`get_scheduled_messages`

`delete_scheduled_message`

`list_inline_buttons`

`press_inline_button`

`list_messages`

`transcribe_voice`

`get_message_context`

`get_send_as`

`forward_message`

`forward_messages`

`edit_message`

`delete_message`

`delete_chat_history`

`delete_messages_bulk`

`pin_message`

`unpin_message`

`unpin_all_messages`

`mark_as_read`

`reply_to_message`

`search_messages`

`search_global`

`get_history`

`get_pinned_messages`

`create_poll`

`send_reaction`

`remove_reaction`

`get_message_reactions`

`save_draft`

`get_drafts`

`clear_draft`

`create_group`

`invite_to_group`

`leave_chat`

`get_participants`

`create_channel`

`edit_chat_title`

`edit_chat_photo`

`edit_chat_about`

`delete_chat_photo`

`promote_admin`

`demote_admin`

`ban_user`