Telegram MCP Server
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 13 categories — giving your AI complete read/write access to your Telegram account.
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
Table of Contents
- Installation
- Authentication
- Configuration
- Usage with Claude Code
- Tools Reference
- Media Capabilities
- Full Chat Export
- Claude Code Skill
- Project Structure
- Development
Installation
Requirements: Python 3.10+
# Clone the repository
git clone https://github.com/YOUR_USERNAME/telegram-mcp.git
cd telegram-mcp
# Install with uv (recommended)
uv pip install -e .
# Or with pip
pip install -e .
This installs the telegram-mcp CLI command.
Telegram API Credentials
- Go to https://my.telegram.org
- Sign in and navigate to API development tools
- 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.
Configuration
Usage with Claude Code
Add the server to Claude Code:
claude mcp add telegram-mcp \
-s user \
-e TELEGRAM_API_ID=your_api_id \
-e TELEGRAM_API_HASH=your_api_hash \
-e TELEGRAM_SESSION_PATH=/path/to/telegram \
-e TELEGRAM_DOWNLOAD_DIR=~/Downloads/telegram_downloads \
-- telegram-mcp
Verify the server is connected:
claude mcp list
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)
Media (3 tools)
Chats & Dialogs (10 tools)
Contacts (14 tools)
Groups & Channels (21 tools)
User Profile (7 tools)
Reactions (3 tools)
Drafts (3 tools)
Folders (7 tools)
Privacy (2 tools)
Inline Buttons (2 tools)
Forum Topics (1 tool)
Bots & Stickers (6 tools)
Media Capabilities
The server provides comprehensive media handling across Telegram's rich media types:
Supported Media Types
Media Operations
Download any media from a message:
download_media(chat_id="123456", message_id=789, output_dir="~/Downloads/export")
→ { "path": "~/Downloads/export/photo_2026-02-15.jpg", "name": "photo_2026-02-15.jpg", "size": 245760 }
Inspect media without downloading:
get_media_info(chat_id="123456", message_id=789)
→ { "type": "video", "duration": 45, "width": 1920, "height": 1080, "mime": "video/mp4", "size": 15728640 }
Download profile photos:
download_profile_photo(entity_id="@username", output_dir="~/Downloads/photos")
Full Chat Export
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
- Automatic Rate Limiting — Handles Telegram's FloodWaitError gracefully with automatic retry
- Incremental Progress — Processes messages in batches for memory efficiency
Usage
export_full_chat_history(
chat_id="1508482670",
output_dir="~/Downloads/telegram_export_alice",
include_media=true,
media_types="photo,voice,document"
)
Output Format
{
"chat_id": "1508482670",
"chat_name": "Alice",
"export_date": "2026-02-15T12:00:00",
"total_messages": 4523,
"messages": [
{
"id": 1,
"date": "2024-03-15T09:30:00+00:00",
"sender_id": 376087036,
"text": "Hey Alice!",
"has_media": false
},
{
"id": 2,
"date": "2024-03-15T09:31:00+00:00",
"sender_id": 1508482670,
"text": "",
"has_media": true,
"media_type": "voice",
"media_path": "~/Downloads/telegram_export_alice/media/voice_2.ogg"
}
],
"media_summary": {
"photo": 156,
"voice": 89,
"document": 23,
"total_downloaded": 268
}
}
Targeted Message Retrieval
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:
cp -r telegram_claude_skill/ ~/.claude/skills/telegram/
Then invoke it in Claude Code with /telegram <your request>.
What the Skill Does
The skill acts as an orchestration layer that:
- Parses natural language — Understands intents like "show conversation", "download media", "export history", "search", "send", etc.
- Resolves targets — Finds contacts/groups by name, username, or phone number
- Handles pagination — Automatically iterates through large message sets
- Downloads media — Saves photos, videos, voice messages, and documents locally
- Exports structured JSON — Produces clean, parseable conversation exports with media summaries
- Asks before acting — Always confirms before sending messages or performing destructive operations
See telegram_claude_skill/SKILL.md for the full skill definition.
Project Structure
telegram-mcp/
├── pyproject.toml # Package configuration & dependencies
├── telegram_mcp/
│ ├── __init__.py
│ ├── server.py # FastMCP server entry point (STDIO transport)
│ ├── client.py # Telethon client singleton manager
│ ├── auth.py # Interactive authentication flow
│ └── tools/ # Tool implementations by category
│ ├── chats.py
│ ├── contacts.py
│ ├── messages.py
│ ├── media.py
│ ├── groups.py
│ ├── user_profile.py
│ ├── reactions.py
│ ├── drafts.py
│ ├── folders.py
│ ├── privacy.py
│ ├── buttons.py
│ ├── topics.py
│ ├── bots.py
│ └── stickers.py
├── telegram_claude_skill/ # Claude Code skill for natural language access
│ └── SKILL.md
├── tests/
└── scripts/
└── authenticate.py
Development
# 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
Dependencies
Contributing
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