A fully-featured Model Context Protocol (MCP) server that connects AI assistants to Telegram. Built on Telethon (MTProto) and FastMCP, it exposes 89 tools across — giving your AI complete read/write access to your Telegram account.
Telegram MCP server — 89 tools for AI assistants to interact with Telegram via Telethon MTProto
13 categories
Unlike WhatsApp or other bridges, Telegram stores full chat history server-side. This MCP can access every message from the beginning of any conversation — no sync limitations.
Highlights
Full Chat History Export — Extract entire conversations with structured JSON output, optional media download, and automatic rate-limit handling
Media Download & Management — Download photos, videos, voice messages, documents, stickers, and round videos from any chat
89 Tools, 13 Categories — Chats, contacts, messages, media, groups, user profile, reactions, drafts, folders, privacy, inline buttons, forum topics, and bots/stickers
MTProto Direct Connection — No bridges, no bots, no intermediaries. Direct connection to Telegram's API via Telethon
STDIO Transport — Runs as a local MCP server over standard I/O, compatible with Claude Code and any MCP-compatible client
Create a new application to get your API ID and API Hash
Authentication
Before using the server, authenticate your Telegram account:
# Create a .env file with your credentials
cat > .env << 'EOF'
TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
TELEGRAM_PHONE_NUMBER=+your_phone_number
TELEGRAM_SESSION_PATH=./telegram
TELEGRAM_DOWNLOAD_DIR=./downloads
EOF
# Run the interactive authentication
python -m telegram_mcp.auth
You'll receive a verification code in your Telegram app. Enter it, and optionally provide your 2FA password. This creates a telegram.session file for future automatic authentication.
Once connected, you can interact with Telegram through natural language:
> Show me the last 20 messages from Alice
> Download all photos from "Family Group" for the past week
> Export full chat history with David including all media
> Search for "meeting notes" in group "Work Team"
> Who is in group "Project Alpha"?
> Send "On my way!" to Mom
Tools Reference
Messages (15 tools)
Tool
Description
list_messages
Retrieve messages with pagination, date filtering (offset_date), text search, and sender filtering
search_messages
Full-text search within any chat
get_message_context
Get surrounding messages before/after a specific message
send_message
Send text with Markdown support and optional reply-to
send_file
Send photos, videos, documents, voice, and round videos with captions
edit_message
Edit a previously sent message
delete_messages
Delete messages with optional revoke (delete for everyone)
forward_message
Forward messages to another chat
pin_message
Pin a message with optional silent notification
unpin_message
Unpin a specific or most recent message
get_pinned_messages
Retrieve all pinned messages in a chat
mark_read
Mark all messages in a chat as read
send_reaction
React to a message with emoji
get_media_info
Inspect media metadata without downloading
create_poll
Create polls and quizzes with anonymous/multi-choice modes
Media (3 tools)
Tool
Description
download_media
Download any media attachment (photo, video, document, voice, sticker, round video) from a message. Returns structured JSON with file path, name, and size
download_profile_photo
Download the profile photo of any user, group, or channel
export_full_chat_history
Export an entire conversation — all messages from the beginning of time with optional media download, type filtering, and structured JSON output. Handles rate limits automatically
Chats & Dialogs (10 tools)
Tool
Description
list_dialogs
List all conversations sorted by recent activity, with folder filtering and unread counts
get_chat_info
Full metadata for any chat, group, or channel
get_direct_chat_by_contact
Find the DM conversation with a specific contact
get_contact_chats
Get all chats shared with a contact
get_last_interaction
Find the last message date/details with a contact
archive_chat
Archive a conversation
unarchive_chat
Restore from archive
mute_chat
Mute notifications
unmute_chat
Unmute notifications
search_public_chats
Search for public channels, groups, and users
Contacts (14 tools)
Tool
Description
list_contacts
List all saved contacts
search_contacts
Search by name or username
get_contact_details
Full user info: bio, common chats, block status, profile photos
get_contact_ids
Get numeric IDs for all contacts
add_contact
Add a contact by phone number or username
delete_contact
Remove a contact
import_contacts
Bulk import contacts from a list
export_contacts
Export all contacts as JSON
resolve_username
Resolve an @username to full entity details
block_user / unblock_user
Block or unblock a user
get_blocklist
List all blocked users
Groups & Channels (21 tools)
Tool
Description
create_group
Create a new group or supergroup
create_channel
Create a broadcast channel
get_group_participants
List members with roles (creator, admin, member)
get_admins
List all admins
add_group_members / remove_group_members
Add or remove group members
promote_to_admin / demote_admin
Manage admin rights with custom titles
ban_user / unban_user
Ban or unban users from supergroups
get_banned_users
List banned/kicked users
update_group
Update title and description
edit_chat_photo / delete_chat_photo
Manage group/channel photo
leave_group
Leave a group or channel
subscribe_public_channel
Join a public channel
get_invite_link
Get current invite link
export_chat_invite
Create invite link with expiry, usage limit, and title
import_chat_invite / join_chat_by_link
Join via invite hash or link
User Profile (7 tools)
Tool
Description
get_me
Get your own account info
update_profile
Update first name, last name, and bio
set_profile_photo / delete_profile_photo
Manage profile photo
get_user_status
Check online status (online, recently, last week, etc.)
get_user_photos
Get profile photos metadata
resolve_username
Resolve @username to entity details
Reactions (3 tools)
Tool
Description
send_reaction
React to a message with emoji
remove_reaction
Remove your reaction
get_message_reactions
See all reactions and who reacted
Drafts (3 tools)
Tool
Description
save_draft
Save a message draft with optional reply-to and link preview control
The export_full_chat_history tool is designed for complete conversation extraction — every message from the very first one to the latest, with optional media download.
Features
Complete History — Iterates through the entire conversation from beginning to end
Optional Media Download — Download all media or filter by type (photo, video, voice, audio, document, sticker)
Structured JSON Output — Clean, parseable output with message metadata, sender info, timestamps, and media paths
For more targeted extraction, use list_messages with filters:
# Messages from a specific sender in the past 7 days
list_messages(chat_id="group_id", from_user="alice", offset_date="2026-02-08T00:00:00", limit=0)
# Search for specific content
search_messages(chat_id="group_id", query="meeting notes", limit=50)
# Get context around a specific message
get_message_context(chat_id="group_id", message_id=12345, before=10, after=10)
Claude Code Skill
The telegram_claude_skill/ directory contains a ready-to-use Claude Code skill that gives Claude natural language access to all Telegram MCP tools. Instead of calling tools manually, you can use conversational commands like:
/telegram show conversation with "David" for past 7 days
/telegram download all audio from group "Work Team"
/telegram export full chat history with "Mom"
/telegram search for "deadline" in group "Marketing"
/telegram send "On my way!" to Alice
Installation
Copy the skill into your Claude Code skills directory:
# Install in development mode
uv pip install -e ".[dev]"
# Run tests
pytest tests/
# Run the server directly
python -m telegram_mcp.server
# Or via the CLI entry point
telegram-mcp
This project is actively maintained and contributions are welcome.
If you encounter bugs, unexpected behavior, or have ideas for improvements — whether in the MCP server itself or the Claude Code skill — please don't hesitate to:
Open an issue describing what you ran into or what you'd like to see
Submit a pull request with a fix or enhancement
Even small things help: a tool returning unexpected output, a missing edge case, a better prompt in the skill file, or a Telegram API change that broke something. If you're not sure whether something is a bug or just your setup, open an issue anyway — we'll figure it out together.
License
MIT
T
Telegram
Matancoo·4 ดาว·
Telegram MCP server — 89 tools for AI assistants to interact with Telegram via Telethon MTProto