Hosting

Local Python stdio process by default; optional local/shared Streamable HTTP service or legacy SSE

Transport

stdio by default; optional Streamable HTTP and legacy SSE

Endpoint

Local process; no hosted endpoint documented

Authentication

Requires Telegram API ID and API hash from https://my.telegram.org/apps plus an authorized Telegram session string or file session. Generate the session locally with the repository script using QR login or phone-code login. The session credential grants the server the normal authority of that Telegram account; never share or commit it.

Requirements

• Python 3.10 or later.
• uv and Git for the documented clone-and-run workflow.
• A Telegram account and API credentials created at https://my.telegram.org/apps.
• A locally generated Telegram session string or private file session. Optional voice transcription providers have separate credentials or account requirements.

Setup steps

1. Use only the maintained repository at https://github.com/chigwell/telegram-mcp. Do not install the unrelated PyPI project named telegram-mcp; the repository explicitly warns that it is controlled by another publisher.
2. Install Python 3.10+ and uv, then clone the repository and run `uv sync` in its root directory.
3. Open https://my.telegram.org/apps, sign in to Telegram, and create or copy the API ID and API hash for the app. Keep both values private.
4. From the repository root, run `uv run session_string_generator.py --qr` and scan the QR code with the already signed-in Telegram mobile app, or use `--phone` and complete the Telegram verification prompt. Store the resulting session string securely; it grants account access.
5. Create the local `.env` from `.env.example` and set `TELEGRAM_API_ID`, `TELEGRAM_API_HASH`, and `TELEGRAM_SESSION_STRING`. Do not commit `.env` or a `.session` file.
6. For a least-exposure configuration, set `TELEGRAM_EXPOSED_TOOLS=read-only`; this limits which MCP tools are registered but does not reduce the underlying Telegram session authority. The repository documents that the default `all` setting includes sending, editing, deleting, and account/chat mutation tools.
7. Configure stdio with command `uv` and args `--directory <CLONED_REPOSITORY_PATH> run main.py`, passing the required variables through the client’s secure local environment mechanism. Optional shared Streamable HTTP uses `MCP_TRANSPORT=http` and endpoint `/mcp` after starting the service separately.
8. Reconnect the MCP client and inspect its MCP tool inventory. If a harmless functionality check is later authorized and credentials are present, start with a read-only operation such as listing chats or reading history; do not send messages or modify account data as a connection check.

The maintainer README checked on 2026-10-17 reports 80+ tools. Available names vary with TELEGRAM_EXPOSED_TOOLS and optional features. The entries below are a documented representative subset, not a complete tools/list observation; no MCP connection was attempted.

• get_history

  Read chat history; documented message listings may include already cached voice transcripts.

  01
• get_messages

  Read messages from a chat; documented as including cached transcripts when available.

  02
• list_messages

  List messages with cached transcript metadata when available.

  03
• search_messages

  Search message content within Telegram chats.

  04
• search_global

  Search across Telegram messages.

  05
• get_message_context

  Retrieve surrounding message context.

  06
• send_message

  Send a Telegram message; this changes external account state.

  07
• reply_to_message

  Reply to a Telegram message; this changes external account state.

  08
• edit_message

  Edit a Telegram message; this changes external account state.

  09
• vote_poll

  Vote in a Telegram poll; this can replace an existing vote.

  Parameters: chat_id, message_id, option_indices, account
  10
• transcribe_voice

  Transcribe a voice message with the selected supported engine; external providers may receive audio.

  Parameters: chat_id, message_id, engine
  11

This server’s available tools can vary by account, permissions, or configuration. The list shown is not its full runtime catalog.

• This is a third-party community integration, not a Telegram-operated MCP server.
• A Telegram session string/file has the normal authority of the account and must be protected as a secret. The read-only tool filter only narrows the MCP-exposed surface.
• The default tools include irreversible or externally visible actions such as sending/deleting messages and account/chat changes; require explicit user authorization before those calls.
• Using multiple server processes with the same Telegram session can cause Telegram AuthKeyDuplicatedError; the maintainer recommends a shared HTTP process for multiple MCP clients.
• Voice transcription through Groq or other remote OpenAI-compatible endpoints sends audio to that configured provider; local Whisper avoids that transfer but needs the optional extra and local model resources.
• No connection, tools/list, or representative functionality call was performed; credentials were not requested or used.

• The PyPI distribution named telegram-mcp is owned by an unrelated project and does not install this repository. The maintained README explicitly warns against using that package and notes that passing Telegram credentials to it could expose them to unrelated code; setup therefore uses the exact Git repository checkout and uv workflow.

• maintainer repository documentation

  Documents the repository owner/maintainers, 80+ tools and feature groups, Python 3.10+, clone + uv sync installation, exact credential/session procedure, safe read-only tool-filter setting, client stdio configuration, optional HTTP/SSE transport, and explicit warning that the PyPI name belongs to another project.

• official credential portal

  Linked by the maintained README as the source for the Telegram API ID and API hash needed by this server.

• official branding and media

  Telegram identifies this official press page as the source for high-quality Telegram logos and asks publishers to avoid implying Telegram officially represents the integration. The selected 1000x1000 SVG was taken from the linked official logo archive, decoded, rasterized to 192x192 PNG, and visually reviewed on light and dark backgrounds.

• maintainer or vendor tool reference

  Maintainer repository documents 80+ tools and configurable read-only/tool exposure; stored 11 entries are a partial sample.

Documentation checked 2026-10-28T00:00:00Z. Connection has not been runtime tested.