Log inSubmit server
Telegram MCP logo

Telegram MCP

by chigwell

Manage Telegram accounts, chats, messages, contacts, media, reactions, polls, and admin actions through MCP tools.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Telegram MCP

Pick your client, then add it in one click or paste the config.

STDIOPython
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "chigwell-telegram-mcp": {
      "command": "uvx",
      "args": [
        "telegram-mcp"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

chigwell/telegram-mcp connects Claude, Cursor, and other MCP-compatible clients to Telegram through Telethon. Its 80+ tools cover account routing, chat and group administration, message operations, contacts, media, polls, reactions, inline buttons, and read status. Reach for it when an agent needs to inspect Telegram conversations, perform account actions, or automate carefully controlled messaging workflows. It also supports remembered contact aliases, multiple accounts, typing indicators, and voice-message transcription.

Use cases

  • Summarize unread Telegram conversations
  • Search chat history and retrieve surrounding context
  • Draft or send replies to Telegram messages
  • Manage groups, channels, participants, and permissions
  • Transcribe voice messages and video notes

Key features

  • 80+ Telegram MCP tools
  • Multi-account routing
  • Message, poll, reaction, and inline-button operations
  • Contact aliases with confirmation safeguards
  • Media handling and voice transcription
  • Chat and group administration

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked Today

Recent health check succeeded.

29/29 checks healthy over the last 78d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 9d ago via OSV.dev · telegram-mcp (PyPI)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars1.9kStargazers on the source repository.
Last commitTodayMost recent push to the default branch.
Directory activity10 viewsConfig copies, upvotes, and views on AllMCPs.

How Telegram MCP works

What chigwell/telegram-mcp does

chigwell/telegram-mcp exposes Telegram account and messaging operations through the Model Context Protocol. It is built around Telethon and is intended for use from MCP-compatible clients such as Claude and Cursor. The server includes more than 80 tools spanning account selection, chats, messages, contacts, media, and administrative operations.

Account tools can list configured accounts and route requests using an account label. Chat and group operations include listing conversations, reading metadata, creating groups or channels, joining and leaving chats, managing participants and administrators, changing permissions, working with topics and invite links, and checking common chats. Read receipts, message links, and other chat-level actions are also covered.

How it works

An MCP client invokes Telegram operations as tools, with the server handling the Telegram API through Telethon. Message tools can retrieve history, search conversations, inspect surrounding context, send or schedule messages, edit or delete them, forward content, reply, pin or unpin messages, mark messages read, and manage polls and reactions.

The server supports classic Markdown and HTML formatting, along with richer server-side Markdown and HTML modes that include features such as tables, headings, formulas, and collapsible sections. Rich formatting requires Telegram Premium; when Premium is unavailable, the sending tools return a structured result so the agent can retry using a classic format.

Remembered contact aliases let tools resolve a saved name or tag to a person. Exact saved wording can send directly, while an unfamiliar or merely similar reference produces a confirmation flow instead of sending to a guessed recipient. Aliases are stored in an owner-only JSON file and can be listed, removed, or reassigned with explicit replacement.

Tools and capabilities

  • List configured accounts and route calls by account label.
  • Inspect chats, groups, channels, topics, participants, permissions, and invite links.
  • Send, schedule, edit, delete, forward, pin, reply to, and search messages.
  • Create polls, vote in polls, manage reactions, and inspect or press inline buttons.
  • List, search, add, delete, block, unblock, import, and export contacts.
  • Send and download media, upload files, send voice notes, stickers, and GIFs.
  • Transcribe voice messages and video notes using the available transcription engines.
  • Send temporary typing indicators for a chat or forum topic.
  • Configure and resolve remembered contact aliases.

Limitations and notes

Rich message formatting is restricted to Telegram Premium accounts and is checked for each call. Typing indicators are blocking operations rather than background notifications: the call should complete before sending the related message, and overlapping indicators for the same account, peer, and topic are rejected.

Poll voting uses zero-based option indexes and validates closed polls, invalid selections, duplicate indexes, and single-choice restrictions. Inline-button pressing supports callback and game buttons but refuses buttons that require a two-factor-authentication password.

The contact-alias safety behavior favors avoiding accidental messages. Unknown, ambiguous, or unresolved references result in instructions to confirm or save the intended contact before retrying. Alias storage can be redirected with TELEGRAM_ALIASES_FILE, while TELEGRAM_CONTACT_FUZZY=0 disables similarity suggestions.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Telegram MCP

chigwell/telegram-mcp is an MCP server that connects MCP-compatible clients to Telegram through Telethon. It exposes tools for account and chat management, message retrieval and sending, contacts, media, read status, reactions, polls, inline buttons, and administrative actions across configured Telegram accounts.

Use the project's Quick Start and MCP Client Configuration instructions to set it up for an MCP-compatible client. The server is designed to work with Claude, Cursor, and other MCP clients, and its Telegram operations run through Telethon.

Yes. Cursor is named as a supported MCP-compatible client for this Telegram integration. After configuring the server in Cursor, the client can invoke its account, chat, message, contact, media, and administration tools.

Use remembered contact aliases and confirm unfamiliar references before sending. Exact saved wording can resolve directly, while unknown, ambiguous, or merely similar names return a structured confirmation instruction instead of sending to a guessed recipient. Set `TELEGRAM_CONTACT_FUZZY=0` to disable similarity suggestions.

Yes. The `transcribe_voice` tool converts Telegram voice messages and video notes into text using one of the available transcription engines, with Groq's hosted Whisper engine listed as the default.

Related MCP servers

All in Communication All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewTelegram MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/chigwell-telegram-mcp?style=directory)](https://allmcps.com/mcp/chigwell-telegram-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/chigwell-telegram-mcp"><img src="https://allmcps.com/api/badge/chigwell-telegram-mcp?style=directory" alt="Telegram MCP on AllMCPs" /></a>