Telegram

Telegram

An MCP server enabling paginated chat reading, message retrieval, and sending on Telegram via Telethon.

463
Stars
130
Forks
12
Releases

Overview

Telegram MCP Server is a full-featured integration for Claude, Cursor, and any MCP-compatible client, powered by Telethon and the Model Context Protocol. It exposes a comprehensive suite of Telegram tools, enabling programmatic interaction with Telegram for messaging, group management, and data retrieval. The server offers chat and group management (get_chats, list_chats, create_group, create_channel, edit_chat_title, leave_chat, get_participants, get_admins, invite links, join by link, subscribe_public_channel), messaging operations (get_messages, list_messages, send_message, reply_to_message, edit_message, delete_message, forward_message, pin_message, unpin_message, mark_as_read, get_message_context, get_history, get_pinned_messages), and discovery features (search_public_chats, search_messages, resolve_username). It also provides polls, inline keyboards (list_inline_buttons, press_inline_button) and contact/user management (list_contacts, add_contact, delete_contact, block/unblock, import/export). Input validation for chat_id and user_id improves robustness, and detailed error handling logs issues to mcp_errors.log. The project runs via uv locally or in Docker, and configures credentials through .env. By keeping processing local, it avoids sending data outside Telegram’s API, making it suitable for MCP workflows in Claude/Cursor environments.

Details

Owner
chigwell
Language
Python
License
Apache License 2.0
Updated
2025-12-07

Features

Paginated Chat Reading

Provides get_chats(page, page_size) for a paginated list of chats and get_messages(chat_id, page, page_size) for paginated messages.

Chat & Group Management Toolkit

Supports creating groups/channels, editing titles, managing participants, invite links, and joining via invites.

Messaging & History Operations

Enables sending, replying, editing, deleting, forwarding, pinning/unpinning messages, marking as read, and accessing message context/history.

Polls, Inline Buttons & Interactions

Allows creating polls, inspecting inline buttons, and triggering callbacks by label or index.

Contacts & Profile Management

Manages contacts (list/search/add/delete), plus block/unblock and import/export of contacts.

Public Channels & Invite Linking

Subscribes to public channels, retrieves invite links, and joins via invite links with idempotent behavior.

Search & Discovery

Provides search for public chats/channels/bots, message search, and username-to-ID resolution.

Robust Input Validation & Error Handling

Validates chat_id and user_id formats and logs errors to mcp_errors.log with user-friendly messages.

Audience

DevelopersCreate MCP-compatible Telegram tools and integrate Telethon-powered actions into Claude/Cursor workflows.
AI AgentsLeverage MCP to interact with Telegram via Claude or Cursor for automated decision making and data retrieval.
Telegram UsersAutomate messaging, group management, and data retrieval through MCP-enabled tooling.

Tags

telegrammcptelethonclaudecursortelegram-mcpchat-managementmessagingpollsinline-buttonscontactsprivacydockeruvpython