1<div align="center">
2  <img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&height=200&section=header&text=Telegram%20MCP%20Server&fontSize=50&fontAlignY=35&animation=fadeIn&fontColor=FFFFFF&descAlignY=55&descAlign=62" alt="Telegram MCP Server" width="100%" />
3</div>
4 
5![MCP Badge](https://badge.mcpx.dev)
6[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-green?style=flat-square)](https://opensource.org/licenses/Apache-2.0)
7[![Python Lint & Format Check](https://github.com/chigwell/telegram-mcp/actions/workflows/python-lint-format.yml/badge.svg)](https://github.com/chigwell/telegram-mcp/actions/workflows/python-lint-format.yml)
8[![Docker Build & Compose Validation](https://github.com/chigwell/telegram-mcp/actions/workflows/docker-build.yml/badge.svg)](https://github.com/chigwell/telegram-mcp/actions/workflows/docker-build.yml)
9 
10---
11 
12## 🤖 MCP in Action
13 
14Here's a demonstration of the Telegram MCP capabilities in [Claude](https://docs.anthropic.com/en/docs/agents-and-tools/mcp):
15 
16 **Basic usage example:**
17 
18![Telegram MCP in action](screenshots/1.png)
19 
201. **Example: Asking Claude to analyze chat history and send a response:**
21 
22![Telegram MCP Request](screenshots/2.png)
23 
242. **Successfully sent message to the group:**
25 
26![Telegram MCP Result](screenshots/3.png)
27 
28As you can see, the AI can seamlessly interact with your Telegram account, retrieving and displaying your chats, messages, and other data in a natural way.
29 
30---
31 
32A full-featured Telegram integration for Claude, Cursor, and any MCP-compatible client, powered by [Telethon](https://docs.telethon.dev/) and the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). This project lets you interact with your Telegram account programmatically, automating everything from messaging to group management.
33 
34 
35---
36 
37## 🚀 Features & Tools
38 
39This MCP server exposes a huge suite of Telegram tools. **Every major Telegram/Telethon feature is available as a tool!**
40 
41### Chat & Group Management
42- **get_chats(page, page_size)**: Paginated list of chats
43- **list_chats(chat_type, limit)**: List chats with metadata and filtering
44- **get_chat(chat_id)**: Detailed info about a chat
45- **create_group(title, user_ids)**: Create a new group
46- **invite_to_group(group_id, user_ids)**: Invite users to a group or channel
47- **create_channel(title, about, megagroup)**: Create a channel or supergroup
48- **edit_chat_title(chat_id, title)**: Change chat/group/channel title
49- **delete_chat_photo(chat_id)**: Remove chat/group/channel photo
50- **leave_chat(chat_id)**: Leave a group or channel
51- **get_participants(chat_id)**: List all participants
52- **get_admins(chat_id)**: List all admins
53- **get_banned_users(chat_id)**: List all banned users
54- **promote_admin(chat_id, user_id)**: Promote user to admin
55- **demote_admin(chat_id, user_id)**: Demote admin to user
56- **ban_user(chat_id, user_id)**: Ban user
57- **unban_user(chat_id, user_id)**: Unban user
58- **get_invite_link(chat_id)**: Get invite link
59- **export_chat_invite(chat_id)**: Export invite link
60- **import_chat_invite(hash)**: Join chat by invite hash
61- **join_chat_by_link(link)**: Join chat by invite link
62- **subscribe_public_channel(channel)**: Subscribe to a public channel or supergroup by username or ID
63 
64### Messaging
65- **get_messages(chat_id, page, page_size)**: Paginated messages
66- **list_messages(chat_id, limit, search_query, from_date, to_date)**: Filtered messages
67- **list_topics(chat_id, limit, offset_topic, search_query)**: List forum topics in supergroups
68- **send_message(chat_id, message)**: Send a message
69- **reply_to_message(chat_id, message_id, text)**: Reply to a message
70- **edit_message(chat_id, message_id, new_text)**: Edit your message
71- **delete_message(chat_id, message_id)**: Delete a message
72- **forward_message(from_chat_id, message_id, to_chat_id)**: Forward a message
73- **pin_message(chat_id, message_id)**: Pin a message
74- **unpin_message(chat_id, message_id)**: Unpin a message
75- **mark_as_read(chat_id)**: Mark all as read
76- **get_message_context(chat_id, message_id, context_size)**: Context around a message
77- **get_history(chat_id, limit)**: Full chat history
78- **get_pinned_messages(chat_id)**: List pinned messages
79- **get_last_interaction(contact_id)**: Most recent message with a contact
80- **create_poll(chat_id, question, options, multiple_choice, quiz_mode, public_votes, close_date)**: Create a poll
81- **list_inline_buttons(chat_id, message_id, limit)**: Inspect inline keyboards to discover button text/index
82- **press_inline_button(chat_id, message_id, button_text, button_index)**: Trigger inline keyboard callbacks by label or index
83-  **send_reaction(chat_id, message_id, emoji, big=False)**: Add a reaction to a message
84-  **remove_reaction(chat_id, message_id)**: Remove a reaction from a message
85-  **get_message_reactions(chat_id, message_id, limit=50)**: Get all reactions on a message
86 
87### Contact Management
88- **list_contacts()**: List all contacts
89- **search_contacts(query)**: Search contacts
90- **add_contact(phone, first_name, last_name)**: Add a contact
91- **delete_contact(user_id)**: Delete a contact
92- **block_user(user_id)**: Block a user
93- **unblock_user(user_id)**: Unblock a user
94- **import_contacts(contacts)**: Bulk import contacts
95- **export_contacts()**: Export all contacts as JSON
96- **get_blocked_users()**: List blocked users
97- **get_contact_ids()**: List all contact IDs
98- **get_direct_chat_by_contact(contact_query)**: Find direct chat with a contact
99- **get_contact_chats(contact_id)**: List all chats with a contact
100 
101### User & Profile
102- **get_me()**: Get your user info
103- **update_profile(first_name, last_name, about)**: Update your profile
104- **set_profile_photo(file_path)**: Set a profile photo from an allowed root path
105- **delete_profile_photo()**: Remove your profile photo
106- **get_user_photos(user_id, limit)**: Get a user's profile photos
107- **get_user_status(user_id)**: Get a user's online status
108 
109### Media
110- **get_media_info(chat_id, message_id)**: Get info about media in a message
111- **send_file(chat_id, file_path, caption)**: Send a local file from allowed roots
112- **download_media(chat_id, message_id, file_path)**: Save message media under allowed roots
113- **upload_file(file_path)**: Upload a local file and return upload metadata
114- **send_voice(chat_id, file_path)**: Send `.ogg/.opus` voice note from allowed roots
115- **send_sticker(chat_id, file_path)**: Send `.webp` sticker from allowed roots
116- **edit_chat_photo(chat_id, file_path)**: Update chat photo from allowed roots
117 
118### Search & Discovery
119- **search_public_chats(query, limit)**: Search public chats/channels/bots with a configurable result limit
120- **search_messages(chat_id, query, limit)**: Search messages in a chat
121- **search_global(query, page, page_size)**: Search messages globally with pagination
122- **resolve_username(username)**: Resolve a username to ID
123 
124### Stickers, GIFs, Bots
125- **get_sticker_sets()**: List sticker sets
126- **get_bot_info(bot_username)**: Get info about a bot
127- **set_bot_commands(bot_username, commands)**: Set bot commands (bot accounts only)
128 
129### Privacy, Settings, and Misc
130- **get_privacy_settings()**: Get privacy settings
131- **set_privacy_settings(key, allow_users, disallow_users)**: Set privacy settings
132- **mute_chat(chat_id)**: Mute notifications
133- **unmute_chat(chat_id)**: Unmute notifications
134- **archive_chat(chat_id)**: Archive a chat
135- **unarchive_chat(chat_id)**: Unarchive a chat
136- **get_recent_actions(chat_id)**: Get recent admin actions
137 
138### Drafts
139- **save_draft(chat_id, message, reply_to_msg_id, no_webpage)**: Save a draft message to a chat/channel
140- **get_drafts()**: Get all draft messages across all chats
141- **clear_draft(chat_id)**: Clear/delete a draft from a specific chat
142 
143### Input Validation
144 
145To improve robustness, all functions accepting `chat_id` or `user_id` parameters now include input validation. You can use any of the following formats for these IDs:
146 
147-   **Integer ID**: The direct integer ID for a user, chat, or channel (e.g., `123456789` or `-1001234567890`).
148-   **String ID**: The integer ID provided as a string (e.g., `"123456789"`).
149-   **Username**: The public username for a user or channel (e.g., `"@username"` or `"username"`).
150 
151The server will automatically validate the input and convert it to the correct format before making a request to Telegram. If the input is invalid, a clear error message will be returned.
152 
153## File-path Tools Security Model
154 
155File-path tools are available, but **disabled by default** until allowed roots are configured.
156 
157Supported file-path tools:
158- `send_file`, `download_media`, `set_profile_photo`, `edit_chat_photo`, `send_voice`, `send_sticker`, `upload_file`
159 
160Security semantics (aligned with MCP filesystem server):
161- Server-side allowlist via CLI positional arguments (fallback when Roots API is unsupported).
162- Client-provided MCP Roots replace the server allowlist when available.
163- If the client returns an empty Roots list, file-path tools are disabled (deny-all).
164- All paths are resolved via realpath and must stay inside an allowed root.
165- Traversal/glob-like patterns are rejected (`..`, `*`, `?`, `~`, etc.).
166- Relative paths resolve against the first allowed root.
167- Write tools default to `<first_root>/downloads/` when `file_path` is omitted.
168 
169Example server launch with allowlisted roots:
170```bash
171uv --directory /full/path/to/telegram-mcp run main.py /data/telegram /tmp/telegram-mcp
172```
173 
174GIF tools are currently limited: `get_gif_search` and `send_gif` are available, while `get_saved_gifs` is not implemented due to reliability limits in Telethon/Telegram API interactions.
175 
176---
177 
178## 📋 Requirements
179- Python 3.10+
180- [Telethon](https://docs.telethon.dev/)
181- [MCP Python SDK](https://modelcontextprotocol.io/docs/)
182- [Claude Desktop](https://claude.ai/desktop) or [Cursor](https://cursor.so/) (or any MCP client)
183 
184---
185 
186## 🔧 Installation & Setup
187 
188### 1. Fork & Clone
189 
190```bash
191git clone https://github.com/chigwell/telegram-mcp.git
192cd telegram-mcp
193```
194 
195### 2. Install Dependencies with uv
196 
197```bash
198uv sync
199```
200 
201### 3. Generate a Session String
202 
203```bash
204uv run session_string_generator.py
205```
206Follow the prompts to authenticate and update your `.env` file.
207 
208### 4. Configure .env
209 
210Copy `.env.example` to `.env` and fill in your values:
211 
212```
213TELEGRAM_API_ID=your_api_id_here
214TELEGRAM_API_HASH=your_api_hash_here
215TELEGRAM_SESSION_NAME=anon
216TELEGRAM_SESSION_STRING=your_session_string_here
217```
218Get your API credentials at [my.telegram.org/apps](https://my.telegram.org/apps).
219 
220---
221 
222## 🐳 Running with Docker
223 
224If you have Docker and Docker Compose installed, you can build and run the server in a container, simplifying dependency management.
225 
226### 1. Build the Image
227 
228From the project root directory, build the Docker image:
229 
230```bash
231docker build -t telegram-mcp:latest .
232```
233 
234### 2. Running the Container
235 
236You have two options:
237 
238**Option A: Using Docker Compose (Recommended for Local Use)**
239 
240This method uses the `docker-compose.yml` file and automatically reads your credentials from a `.env` file.
241 
2421.  **Create `.env` File:** Ensure you have a `.env` file in the project root containing your `TELEGRAM_API_ID`, `TELEGRAM_API_HASH`, and `TELEGRAM_SESSION_STRING` (or `TELEGRAM_SESSION_NAME`). Use `.env.example` as a template.
2432.  **Run Compose:**
244    ```bash
245    docker compose up --build
246    ```
247    *   Use `docker compose up -d` to run in detached mode (background).
248    *   Press `Ctrl+C` to stop the server.
249 
250**Option B: Using `docker run`**
251 
252You can run the container directly, passing credentials as environment variables.
253 
254```bash
255docker run -it --rm \
256  -e TELEGRAM_API_ID="YOUR_API_ID" \
257  -e TELEGRAM_API_HASH="YOUR_API_HASH" \
258  -e TELEGRAM_SESSION_STRING="YOUR_SESSION_STRING" \
259  telegram-mcp:latest
260```
261*   Replace placeholders with your actual credentials.
262*   Use `-e TELEGRAM_SESSION_NAME=your_session_file_name` instead of `TELEGRAM_SESSION_STRING` if you prefer file-based sessions (requires volume mounting, see `docker-compose.yml` for an example).
263*   The `-it` flags are crucial for interacting with the server.
264 
265---
266 
267## ⚙️ Configuration for Claude & Cursor
268 
269### MCP Configuration
270Edit your Claude desktop config (e.g. `~/Library/Application Support/Claude/claude_desktop_config.json`) or Cursor config (`~/.cursor/mcp.json`):
271 
272```json
273{
274  "mcpServers": {
275    "telegram-mcp": {
276      "command": "uv",
277      "args": [
278        "--directory",
279        "/full/path/to/telegram-mcp",
280        "run",
281        "main.py"
282      ]
283    }
284  }
285}
286```
287 
288## 📝 Tool Examples with Code & Output
289 
290Below are examples of the most commonly used tools with their implementation and sample output.
291 
292### Getting Your Chats
293 
294```python
295@mcp.tool()
296async def get_chats(page: int = 1, page_size: int = 20) -> str:
297    """
298    Get a paginated list of chats.
299    Args:
300        page: Page number (1-indexed).
301        page_size: Number of chats per page.
302    """
303    try:
304        dialogs = await client.get_dialogs()
305        start = (page - 1) * page_size
306        end = start + page_size
307        if start >= len(dialogs):
308            return "Page out of range."
309        chats = dialogs[start:end]
310        lines = []
311        for dialog in chats:
312            entity = dialog.entity
313            chat_id = entity.id
314            title = getattr(entity, "title", None) or getattr(entity, "first_name", "Unknown")
315            lines.append(f"Chat ID: {chat_id}, Title: {title}")
316        return "\n".join(lines)
317    except Exception as e:
318        logger.exception(f"get_chats failed (page={page}, page_size={page_size})")
319        return "An error occurred (code: GETCHATS-ERR-001). Check mcp_errors.log for details."
320```
321 
322Example output:
323```
324Chat ID: 123456789, Title: John Doe
325Chat ID: -100987654321, Title: My Project Group
326Chat ID: 111223344, Title: Jane Smith
327Chat ID: -200123456789, Title: News Channel
328```
329 
330### Sending Messages
331 
332```python
333@mcp.tool()
334async def send_message(chat_id: int, message: str) -> str:
335    """
336    Send a message to a specific chat.
337    Args:
338        chat_id: The ID of the chat.
339        message: The message content to send.
340    """
341    try:
342        entity = await client.get_entity(chat_id)
343        await client.send_message(entity, message)
344        return "Message sent successfully."
345    except Exception as e:
346        logger.exception(f"send_message failed (chat_id={chat_id})")
347        return "An error occurred (code: SENDMSG-ERR-001). Check mcp_errors.log for details."
348```
349 
350Example output:
351```
352Message sent successfully.
353```
354 
355### Listing Inline Buttons
356 
357```python
358@mcp.tool()
359async def list_inline_buttons(
360    chat_id: Union[int, str],
361    message_id: Optional[int] = None,
362    limit: int = 20,
363) -> str:
364    """
365    Discover inline keyboard layout, including button indices, callback availability, and URLs.
366    """
367```
368 
369Example usage:
370```
371list_inline_buttons(chat_id="@sample_tasks_bot")
372```
373 
374This returns something like:
375```
376Buttons for message 42 (date 2025-01-01 12:00:00+00:00):
377[0] text='📋 View tasks', callback=yes
378[1] text='ℹ️ Help', callback=yes
379[2] text='🌐 Visit site', callback=no, url=https://example.org
380```
381 
382### Pressing Inline Buttons
383 
384```python
385@mcp.tool()
386async def press_inline_button(
387    chat_id: Union[int, str],
388    message_id: Optional[int] = None,
389    button_text: Optional[str] = None,
390    button_index: Optional[int] = None,
391) -> str:
392    """
393    Press an inline keyboard button by label or zero-based index.
394    If message_id is omitted, the server searches recent messages for the latest inline keyboard.
395    """
396```
397 
398Example usage:
399```
400press_inline_button(chat_id="@sample_tasks_bot", button_text="📋 View tasks")
401```
402 
403Use `list_inline_buttons` first if you need to inspect available buttons—pass a bogus `button_text`
404to quickly list options or call `list_inline_buttons` directly. Once you know the text or index,
405`press_inline_button` sends the callback, just like tapping the button in a native Telegram client.
406 
407### Subscribing to Public Channels
408 
409```python
410@mcp.tool()
411async def