Repolode
Submit
chigwell

chigwell/telegram-mcp

An MCP server built on Telethon that lets AI clients like Claude and Cursor read Telegram chats and manage groups, messages, media and contacts.

View on GitHub
Stars
1,850
Forks
470
Open issues
31
Last commit
yesterday

What is it?

Telegram MCP Server is an integration that exposes Telegram account, chat, message, contact, media, folder and admin operations to MCP-compatible clients such as Claude Desktop and Cursor. It is built on Telethon and offers 80+ tools covering chats and groups, messages (send, edit, forward, search, polls, reactions), contacts, media, profile and privacy settings, and Telegram folders.

The server supports multiple accounts routed by label, and can be restricted to a read-only tool surface or an allowlist of chats. It can run over stdio, streamable HTTP or SSE, and includes optional voice message transcription through Groq, Telegram Premium, OpenAI-compatible endpoints or a local faster-whisper model. Sessions can be stored as strings or persistent SQLite files, with proxy support for SOCKS, HTTP and MTProxy.

Sending and modifying messages through an AI agent carries real risk, so the project offers controls such as read-only mode, file extension allowlists and allowed roots for file access.

Key features

  • 01Exposes 80+ MCP tools for chats, groups, messages, contacts, media and folders.
  • 02Supports multiple Telegram accounts routed by label.
  • 03Offers a read-only mode and per-tool allowlists to limit write operations.
  • 04Transcribes voice messages via Groq, Telegram Premium, OpenAI-compatible APIs or local Whisper.
  • 05Runs over stdio, streamable HTTP or SSE transports.
  • 06Supports SOCKS, HTTP and MTProxy proxies.

Use cases

  • Letting Claude or Cursor summarize unread Telegram messages and draft replies.
  • Searching chat history and pulling context for an AI assistant.
  • Automating group administration such as invites, permissions and bans.
  • Sharing one Telegram server across several coding-agent sessions over HTTP.

Quick start

  1. 1

    Clone the repository

  2. 2

    Install dependencies with uv

    uv sync
  3. 3

    Run the server

Things to know

  • Requires a Telegram API ID and hash, and some features need Telegram Premium.
  • Several transcription engines and rich formatting depend on paid or API-key services.

Topics

#mcp#telegram#telethon#messaging#chat-management#ai-agent#voice-transcription#admin#api#contacts

FAQ

What is telegram-mcp?
An MCP server built on Telethon that lets AI clients like Claude and Cursor read Telegram chats and manage groups, messages, media and contacts. Telegram MCP Server is an integration that exposes Telegram account, chat, message, contact, media, folder and admin operations to MCP-compatible clients such as Claude Desktop and Cursor. It is built on Telethon and offers 80+ tools covering chats and groups, messages (send, edit, forward, search, polls, reactions), contacts, media, profile and privacy settings, and Telegram folders.
Is telegram-mcp free to use? What license does it have?
telegram-mcp is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is telegram-mcp still maintained?
Actively maintained. The last commit to telegram-mcp was on Oct 19, 2026.
What can I use telegram-mcp for?
Letting Claude or Cursor summarize unread Telegram messages and draft replies. Searching chat history and pulling context for an AI assistant. Automating group administration such as invites, permissions and bans. Sharing one Telegram server across several coding-agent sessions over HTTP.
How do I install telegram-mcp?
Clone the repository Install dependencies with uv: uv sync Run the server
Where can I get telegram-mcp?
The source code and installation instructions are on GitHub: https://github.com/chigwell/telegram-mcp

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects