Content
# Telegram MCP Server
A fully-featured [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that connects AI assistants to Telegram. Built on [Telethon](https://github.com/LonamiWebs/Telethon) (MTProto) and [FastMCP](https://github.com/jlowin/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](#installation)
- [Authentication](#authentication)
- [Configuration](#configuration)
- [Usage with Claude Code](#usage-with-claude-code)
- [Tools Reference](#tools-reference)
- [Messages (15 tools)](#messages-15-tools)
- [Media (3 tools)](#media-3-tools)
- [Chats & Dialogs (10 tools)](#chats--dialogs-10-tools)
- [Contacts (14 tools)](#contacts-14-tools)
- [Groups & Channels (21 tools)](#groups--channels-21-tools)
- [User Profile (7 tools)](#user-profile-7-tools)
- [Reactions (3 tools)](#reactions-3-tools)
- [Drafts (3 tools)](#drafts-3-tools)
- [Folders (7 tools)](#folders-7-tools)
- [Privacy (2 tools)](#privacy-2-tools)
- [Inline Buttons (2 tools)](#inline-buttons-2-tools)
- [Forum Topics (1 tool)](#forum-topics-1-tool)
- [Bots & Stickers (6 tools)](#bots--stickers-6-tools)
- [Media Capabilities](#media-capabilities)
- [Full Chat Export](#full-chat-export)
- [Claude Code Skill](#claude-code-skill)
- [Project Structure](#project-structure)
- [Development](#development)
---
## Installation
**Requirements:** Python 3.10+
```bash
# 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
1. Go to [https://my.telegram.org](https://my.telegram.org)
2. Sign in and navigate to **API development tools**
3. Create a new application to get your **API ID** and **API Hash**
---
## Authentication
Before using the server, authenticate your Telegram account:
```bash
# 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
| Environment Variable | Description | Default |
|---------------------|-------------|---------|
| `TELEGRAM_API_ID` | Telegram API ID (required) | — |
| `TELEGRAM_API_HASH` | Telegram API Hash (required) | — |
| `TELEGRAM_PHONE_NUMBER` | Phone number for auth | — |
| `TELEGRAM_SESSION_PATH` | Path to session file (without `.session` extension) | `./telegram` |
| `TELEGRAM_DOWNLOAD_DIR` | Default directory for media downloads | `./downloads` |
---
## Usage with Claude Code
Add the server to Claude Code:
```bash
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:
```bash
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)
| 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 |
| `get_drafts` | Get all drafts across all chats |
| `clear_draft` | Delete a draft |
### Folders (7 tools)
| Tool | Description |
|------|-------------|
| `list_folders` | List all chat folders |
| `get_folder` | Detailed folder info with peer lists |
| `create_folder` | Create folder with rich filter options (contacts, groups, channels, bots, exclude muted/read/archived, emoji icon) |
| `delete_folder` | Delete a folder |
| `reorder_folders` | Reorder folders |
| `add_chat_to_folder` / `remove_chat_from_folder` | Manage folder contents |
### Privacy (2 tools)
| Tool | Description |
|------|-------------|
| `get_privacy_settings` | Get privacy rules for: status, phone, profile photo, forwards, calls, P2P calls, group invites, bio |
| `set_privacy_settings` | Update rules to: allow all, allow contacts only, or disallow all |
### Inline Buttons (2 tools)
| Tool | Description |
|------|-------------|
| `list_inline_buttons` | Inspect inline keyboard buttons on a message (text, callback, URLs) |
| `press_inline_button` | Click an inline button by text or index, returns bot callback response |
### Forum Topics (1 tool)
| Tool | Description |
|------|-------------|
| `list_topics` | List forum topics in supergroups with search and pagination |
### Bots & Stickers (6 tools)
| Tool | Description |
|------|-------------|
| `get_bot_info` | Get bot description, commands, and verification status |
| `set_bot_commands` | Set commands for your own bot |
| `get_sticker_sets` | List installed sticker packs |
| `send_sticker` | Send a sticker file (.webp, .tgs, .webm) |
| `search_gifs` | Search for GIFs via Telegram's inline bot |
| `send_gif` | Send a GIF by document ID |
---
## Media Capabilities
The server provides comprehensive media handling across Telegram's rich media types:
### Supported Media Types
| Type | Download | Send | Metadata |
|------|----------|------|----------|
| Photos | Yes | Yes | Dimensions, file size |
| Videos | Yes | Yes | Duration, dimensions, codec |
| Voice Messages | Yes | Yes | Duration, codec |
| Round Videos (video notes) | Yes | Yes | Duration, dimensions |
| Documents / Files | Yes | Yes | MIME type, file name, size |
| Stickers | Yes | Yes | Emoji, pack name, animated/video |
| GIFs | Yes | Yes | Via inline bot search |
| Profile Photos | Yes | Yes | Per-user or per-group |
### 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
```json
{
"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/`](./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:
```bash
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:
1. **Parses natural language** — Understands intents like "show conversation", "download media", "export history", "search", "send", etc.
2. **Resolves targets** — Finds contacts/groups by name, username, or phone number
3. **Handles pagination** — Automatically iterates through large message sets
4. **Downloads media** — Saves photos, videos, voice messages, and documents locally
5. **Exports structured JSON** — Produces clean, parseable conversation exports with media summaries
6. **Asks before acting** — Always confirms before sending messages or performing destructive operations
See [`telegram_claude_skill/SKILL.md`](./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
```bash
# 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
| Package | Purpose |
|---------|---------|
| [telethon](https://github.com/LonamiWebs/Telethon) | Telegram MTProto client |
| [fastmcp](https://github.com/jlowin/fastmcp) | MCP server framework |
| [pydantic](https://docs.pydantic.dev/) | Data validation |
| [python-dotenv](https://github.com/theskumar/python-dotenv) | Environment variable loading |
| [aiofiles](https://github.com/Tinche/aiofiles) | Async file I/O |
| [cryptg](https://github.com/cher-nov/cryptg) | Encryption acceleration |
---
## 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:
>
> 1. **Open an issue** describing what you ran into or what you'd like to see
> 2. **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
