MCP Servers | MCP Explorer

Featured MCP Servers

Explore pre-built MCP servers for popular enterprise systems that connect AI assistants to your data sources.

Telegram MCP Server

<div class="markdown-heading"><h1 class="heading-element">Telegram MCP Server</h1><a id="user-content-telegram-mcp-server" class="anchor" aria-label="Permalink: Telegram MCP Server" href="#telegram-mcp-server"></a></div>
<a target="_blank" rel="noopener noreferrer nofollow" href="https://camo.githubusercontent.com/16993b00a5060330fd9ce7dfb8887813e41d… src="https://camo.githubusercontent.com/16993b00a5060330fd9ce7dfb8887813e41d…; alt="MCP Badge" data-canonical-src="https://badge.mcpx.dev" style="max-width: 100%;"></a>
<a href="https://opensource.org/licenses/Apache-2.0" rel="nofollow"><img src="https://camo.githubusercontent.com/41a3bb992d2808d6ddea9f1ed7b7bc8da6d9…; alt="License: Apache 2.0" data-canonical-src="https://img.shields.io/badge/license-Apache%202.0-green?style=flat-squa…; style="max-width: 100%;"></a>
<a href="https://github.com/chigwell/telegram-mcp/actions/workflows/python-lint-… src="https://github.com/chigwell/telegram-mcp/actions/workflows/python-lint-…; alt="Python Lint & Format Check" style="max-width: 100%;"></a>
<a href="https://github.com/chigwell/telegram-mcp/actions/workflows/docker-build… src="https://github.com/chigwell/telegram-mcp/actions/workflows/docker-build…; alt="Docker Build & Compose Validation" style="max-width: 100%;"></a>
<hr>
<div class="markdown-heading"><h2 class="heading-element">🤖 MCP in Action</h2><a id="user-content--mcp-in-action" class="anchor" aria-label="Permalink: 🤖 MCP in Action" href="#-mcp-in-action"></a></div>
Here's a demonstration of the Telegram MCP capabilities in <a href="https://docs.anthropic.com/en/docs/agents-and-tools/mcp" rel="nofollow">Claude</a>:
Basic usage example:
<a target="_blank" rel="noopener noreferrer" href="screenshots/1.png"><img src="screenshots/1.png" alt="Telegram MCP in action" style="max-width: 100%;"></a>
<ol>
<li>Example: Asking Claude to analyze chat history and send a response:</li>
</ol>
<a target="_blank" rel="noopener noreferrer" href="screenshots/2.png"><img src="screenshots/2.png" alt="Telegram MCP Request" style="max-width: 100%;"></a>
<ol start="2">
<li>Successfully sent message to the group:</li>
</ol>
<a target="_blank" rel="noopener noreferrer" href="screenshots/3.png"><img src="screenshots/3.png" alt="Telegram MCP Result" style="max-width: 100%;"></a>
As 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.
<hr>
A full-featured Telegram integration for Claude, Cursor, and any MCP-compatible client, powered by <a href="https://docs.telethon.dev/" rel="nofollow">Telethon</a> and the <a href="https://modelcontextprotocol.io/" rel="nofollow">Model Context Protocol (MCP)</a>. This project lets you interact with your Telegram account programmatically, automating everything from messaging to group management.
<hr>
<div class="markdown-heading"><h2 class="heading-element">🚀 Features & Tools</h2><a id="user-content--features--tools" class="anchor" aria-label="Permalink: 🚀 Features & Tools" href="#-features--tools"></a></div>
This MCP server exposes a huge suite of Telegram tools. Every major Telegram/Telethon feature is available as a tool!
<div class="markdown-heading"><h3 class="heading-element">Chat & Group Management</h3><a id="user-content-chat--group-management" class="anchor" aria-label="Permalink: Chat & Group Management" href="#chat--group-management"></a></div>
<ul>
<li>
get_chats(page, page_size): Paginated list of chats</li>
<li>
list_chats(chat_type, limit): List chats with metadata and filtering</li>
<li>
get_chat(chat_id): Detailed info about a chat</li>
<li>
create_group(title, user_ids): Create a new group</li>
<li>
create_channel(title, about, megagroup): Create a channel or supergroup</li>
<li>
edit_chat_title(chat_id, title): Change chat/group/channel title</li>
<li>
delete_chat_photo(chat_id): Remove chat/group/channel photo</li>
<li>
leave_chat(chat_id): Leave a group or channel</li>
<li>
get_participants(chat_id): List all participants</li>
<li>
get_admins(chat_id): List all admins</li>
<li>
get_banned_users(chat_id): List all banned users</li>
<li>
promote_admin(chat_id, user_id): Promote user to admin</li>
<li>
demote_admin(chat_id, user_id): Demote admin to user</li>
<li>
ban_user(chat_id, user_id): Ban user</li>
<li>
unban_user(chat_id, user_id): Unban user</li>
<li>
get_invite_link(chat_id): Get invite link</li>
<li>
export_chat_invite(chat_id): Export invite link</li>
<li>
import_chat_invite(hash): Join chat by invite hash</li>
<li>
join_chat_by_link(link): Join chat by invite link</li>
</ul>
<div class="markdown-heading"><h3 class="heading-element">Messaging</h3><a id="user-content-messaging" class="anchor" aria-label="Permalink: Messaging" href="#messaging"></a></div>
<ul>
<li>
get_messages(chat_id, page, page_size): Paginated messages</li>
<li>
list_messages(chat_id, limit, search_query, from_date, to_date): Filtered messages</li>
<li>
send_message(chat_id, message): Send a message</li>
<li>
reply_to_message(chat_id, message_id, text): Reply to a message</li>
<li>
edit_message(chat_id, message_id, new_text): Edit your message</li>
<li>
delete_message(chat_id, message_id): Delete a message</li>
<li>
forward_message(from_chat_id, message_id, to_chat_id): Forward a message</li>
<li>
pin_message(chat_id, message_id): Pin a message</li>
<li>
unpin_message(chat_id, message_id): Unpin a message</li>
<li>
mark_as_read(chat_id): Mark all as read</li>
<li>
get_message_context(chat_id, message_id, context_size): Context around a message</li>
<li>
get_history(chat_id, limit): Full chat history</li>
<li>
get_pinned_messages(chat_id): List pinned messages</li>
<li>
get_last_interaction(contact_id): Most recent message with a contact</li>
</ul>
<div class="markdown-heading"><h3 class="heading-element">Contact Management</h3><a id="user-content-contact-management" class="anchor" aria-label="Permalink: Contact Management" href="#contact-management"></a></div>
<ul>
<li>
list_contacts(): List all contacts</li>
<li>
search_contacts(query): Search contacts</li>
<li>
add_contact(phone, first_name, last_name): Add a contact</li>
<li>
delete_contact(user_id): Delete a contact</li>
<li>
block_user(user_id): Block a user</li>
<li>
unblock_user(user_id): Unblock a user</li>
<li>
import_contacts(contacts): Bulk import contacts</li>
<li>
export_contacts(): Export all contacts as JSON</li>
<li>
get_blocked_users(): List blocked users</li>
<li>
get_contact_ids(): List all contact IDs</li>
<li>
get_direct_chat_by_contact(contact_query): Find direct chat with a contact</li>
<li>
get_contact_chats(contact_id): List all chats with a contact</li>
</ul>
<div class="markdown-heading"><h3 class="heading-element">User & Profile</h3><a id="user-content-user--profile" class="anchor" aria-label="Permalink: User & Profile" href="#user--profile"></a></div>
<ul>
<li>
get_me(): Get your user info</li>
<li>
update_profile(first_name, last_name, about): Update your profile</li>
<li>
delete_profile_photo(): Remove your profile photo</li>
<li>
get_user_photos(user_id, limit): Get a user's profile photos</li>
<li>
get_user_status(user_id): Get a user's online status</li>
</ul>
<div class="markdown-heading"><h3 class="heading-element">Media</h3><a id="user-content-media" class="anchor" aria-label="Permalink: Media" href="#media"></a></div>
<ul>
<li>
get_media_info(chat_id, message_id): Get info about media in a message</li>
</ul>
<div class="markdown-heading"><h3 class="heading-element">Search & Discovery</h3><a id="user-content-search--discovery" class="anchor" aria-label="Permalink: Search & Discovery" href="#search--discovery"></a></div>
<ul>
<li>
search_public_chats(query): Search public chats/channels/bots</li>
<li>
search_messages(chat_id, query, limit): Search messages in a chat</li>
<li>
resolve_username(username): Resolve a username to ID</li>
</ul>
<div class="markdown-heading"><h3 class="heading-element">Stickers, GIFs, Bots</h3><a id="user-content-stickers-gifs-bots" class="anchor" aria-label="Permalink: Stickers, GIFs, Bots" href="#stickers-gifs-bots"></a></div>
<ul>
<li>
get_sticker_sets(): List sticker sets</li>
<li>
get_bot_info(bot_username): Get info about a bot</li>
<li>
set_bot_commands(bot_username, commands): Set bot commands (bot accounts only)</li>
</ul>
<div class="markdown-heading"><h3 class="heading-element">Privacy, Settings, and Misc</h3><a id="user-content-privacy-settings-and-misc" class="anchor" aria-label="Permalink: Privacy, Settings, and Misc" href="#privacy-settings-and-misc"></a></div>
<ul>
<li>
get_privacy_settings(): Get privacy settings</li>
<li>
set_privacy_settings(key, allow_users, disallow_users): Set privacy settings</li>
<li>
mute_chat(chat_id): Mute notifications</li>
<li>
unmute_chat(chat_id): Unmute notifications</li>
<li>
archive_chat(chat_id): Archive a chat</li>
<li>
unarchive_chat(chat_id): Unarchive a chat</li>
<li>
get_recent_actions(chat_id): Get recent admin actions</li>
</ul>
<div class="markdown-heading"><h2 class="heading-element">Removed Functionality</h2><a id="user-content-removed-functionality" class="anchor" aria-label="Permalink: Removed Functionality" href="#removed-functionality"></a></div>
Please note that tools requiring direct file path access on the server (<code>send_file</code>, <code>download_media</code>, <code>set_profile_photo</code>, <code>edit_chat_photo</code>, <code>send_voice</code>, <code>send_sticker</code>, <code>upload_file</code>) have been removed from <code>main.py</code>. This is due to limitations in the current MCP environment regarding handling file attachments and local file system paths.
Additionally, GIF-related tools (<code>get_gif_search</code>, <code>get_saved_gifs</code>, <code>send_gif</code>) have been removed due to ongoing issues with reliability in the Telethon library or Telegram API interactions.
<hr>
<div class="markdown-heading"><h2 class="heading-element">📋 Requirements</h2><a id="user-content--requirements" class="anchor" aria-label="Permalink: 📋 Requirements" href="#-requirements"></a></div>
<ul>
<li>Python 3.10+</li>
<li><a href="https://docs.telethon.dev/" rel="nofollow">Telethon</a></li>
<li><a href="https://modelcontextprotocol.io/docs/" rel="nofollow">MCP Python SDK</a></li>
<li>
<a href="https://claude.ai/desktop" rel="nofollow">Claude Desktop</a> or <a href="https://cursor.so/" rel="nofollow">Cursor</a> (or any MCP client)</li>
</ul>
<hr>
<div class="markdown-heading"><h2 class="heading-element">🔧 Installation & Setup</h2><a id="user-content--installation--setup" class="anchor" aria-label="Permalink: 🔧 Installation & Setup" href="#-installation--setup"></a></div>
<div class="markdown-heading"><h3 class="heading-element">1. Fork & Clone</h3><a id="user-content-1-fork--clone" class="anchor" aria-label="Permalink: 1. Fork & Clone" href="#1-fork--clone"></a></div>
<div class="highlight highlight-source-shell"><pre>git clone https://github.com/chigwell/telegram-mcp.git
cd telegram-mcp</pre></div>
<div class="markdown-heading"><h3 class="heading-element">2. Create a Virtual Environment</h3><a id="user-content-2-create-a-virtual-environment" class="anchor" aria-label="Permalink: 2. Create a Virtual Environment" href="#2-create-a-virtual-environment"></a></div>
<div class="highlight highlight-source-shell"><pre>python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -r requirements.txt</pre></div>
<div class="markdown-heading"><h3 class="heading-element">3. Generate a Session String</h3><a id="user-content-3-generate-a-session-string" class="anchor" aria-label="Permalink: 3. Generate a Session String" href="#3-generate-a-session-string"></a></div>
<div class="highlight highlight-source-shell"><pre>python3 session_string_generator.py</pre></div>
Follow the prompts to authenticate and update your <code>.env</code> file.
<div class="markdown-heading"><h3 class="heading-element">4. Configure .env</h3><a id="user-content-4-configure-env" class="anchor" aria-label="Permalink: 4. Configure .env" href="#4-configure-env"></a></div>
Copy <code>.env.example</code> to <code>.env</code> and fill in your values:
<pre><code>TELEGRAM_API_ID=your_api_id_here
TELEGRAM_API_HASH=your_api_hash_here
TELEGRAM_SESSION_NAME=anon
TELEGRAM_SESSION_STRING=your_session_string_here
</code></pre>
Get your API credentials at <a href="https://my.telegram.org/apps" rel="nofollow">my.telegram.org/apps</a>.
<hr>
<div class="markdown-heading"><h2 class="heading-element">🐳 Running with Docker</h2><a id="user-content--running-with-docker" class="anchor" aria-label="Permalink: 🐳 Running with Docker" href="#-running-with-docker"></a></div>
If you have Docker and Docker Compose installed, you can build and run the server in a container, simplifying dependency management.
<div class="markdown-heading"><h3 class="heading-element">1. Build the Image</h3><a id="user-content-1-build-the-image" class="anchor" aria-label="Permalink: 1. Build the Image" href="#1-build-the-image"></a></div>
From the project root directory, build the Docker image:
<div class="highlight highlight-source-shell"><pre>docker build -t telegram-mcp:latest .</pre></div>
<div class="markdown-heading"><h3 class="heading-element">2. Running the Container</h3><a id="user-content-2-running-the-container" class="anchor" aria-label="Permalink: 2. Running the Container" href="#2-running-the-container"></a></div>
You have two options:
Option A: Using Docker Compose (Recommended for Local Use)
This method uses the <code>docker-compose.yml</code> file and automatically reads your credentials from a <code>.env</code> file.
<ol>
<li>
Create <code>.env</code> File: Ensure you have a <code>.env</code> file in the project root containing your <code>TELEGRAM_API_ID</code>, <code>TELEGRAM_API_HASH</code>, and <code>TELEGRAM_SESSION_STRING</code> (or <code>TELEGRAM_SESSION_NAME</code>). Use <code>.env.example</code> as a template.</li>
<li>
Run Compose:
<div class="highlight highlight-source-shell"><pre>docker compose up --build</pre></div>
<ul>
<li>Use <code>docker compose up -d</code> to run in detached mode (background).</li>
<li>Press <code>Ctrl+C</code> to stop the server.</li>
</ul>
</li>
</ol>
Option B: Using <code>docker run</code>
You can run the container directly, passing credentials as environment variables.
<div class="highlight highlight-source-shell"><pre>docker run -it --rm \
-e TELEGRAM_API_ID="YOUR_API_ID" \
-e TELEGRAM_API_HASH="YOUR_API_HASH" \
-e TELEGRAM_SESSION_STRING="YOUR_SESSION_STRING" \
telegram-mcp:latest</pre></div>
<ul>
<li>Replace placeholders with your actual credentials.</li>
<li>Use <code>-e TELEGRAM_SESSION_NAME=your_session_file_name</code> instead of <code>TELEGRAM_SESSION_STRING</code> if you prefer file-based sessions (requires volume mounting, see <code>docker-compose.yml</code> for an example).</li>
<li>The <code>-it</code> flags are crucial for interacting with the server.</li>
</ul>
<hr>
<div class="markdown-heading"><h2 class="heading-element">⚙️ Configuration for Claude & Cursor</h2><a id="user-content-️-configuration-for-claude--cursor" class="anchor" aria-label="Permalink: ⚙️ Configuration for Claude & Cursor" href="#️-configuration-for-claude--cursor"></a></div>
<div class="markdown-heading"><h3 class="heading-element">MCP Configuration</h3><a id="user-content-mcp-configuration" class="anchor" aria-label="Permalink: MCP Configuration" href="#mcp-configuration"></a></div>
Edit your Claude desktop config (e.g. <code>~/Library/Application Support/Claude/claude_desktop_config.json</code>) or Cursor config (<code>~/.cursor/mcp.json</code>):
<div class="highlight highlight-source-json"><pre>{
"mcpServers": {
"telegram-mcp": {
"command": "uv",
"args": [
"--directory",
"/full/path/to/telegram-mcp",
"run",
"main.py"
]
}
}
}</pre></div>
<div class="markdown-heading"><h2 class="heading-element">📝 Tool Examples with Code & Output</h2><a id="user-content--tool-examples-with-code--output" class="anchor" aria-label="Permalink: 📝 Tool Examples with Code & Output" href="#-tool-examples-with-code--output"></a></div>
Below are examples of the most commonly used tools with their implementation and sample output.
<div class="markdown-heading"><h3 class="heading-element">Getting Your Chats</h3><a id="user-content-getting-your-chats" class="anchor" aria-label="Permalink: Getting Your Chats" href="#getting-your-chats"></a></div>
<div class="highlight highlight-source-python"><pre>@mcp.tool()
async def get_chats(page: int = 1, page_size: int = 20) -> str:
"""
 Get a paginated list of chats.
 Args:
 page: Page number (1-indexed).
 page_size: Number of chats per page.
 """
try:
dialogs = await client.get_dialogs()
start = (page - 1) * page_size
end = start + page_size
if start >= len(dialogs):
return "Page out of range."
chats = dialogs[start:end]
lines = []
for dialog in chats:
entity = dialog.entity
chat_id = entity.id
title = getattr(entity, "title", None) or getattr(entity, "first_name", "Unknown")
lines.append(f"Chat ID: {chat_id}, Title: {title}")
return "\n".join(lines)
except Exception as e:
logger.exception(f"get_chats failed (page={page}, page_size={page_size})")
return "An error occurred (code: GETCHATS-ERR-001). Check mcp_errors.log for details."</pre></div>
Example output:
<pre><code>Chat ID: 123456789, Title: John Doe
Chat ID: -100987654321, Title: My Project Group
Chat ID: 111223344, Title: Jane Smith
Chat ID: -200123456789, Title: News Channel
</code></pre>
<div class="markdown-heading"><h3 class="heading-element">Sending Messages</h3><a id="user-content-sending-messages" class="anchor" aria-label="Permalink: Sending Messages" href="#sending-messages"></a></div>
<div class="highlight highlight-source-python"><pre>@mcp.tool()
async def send_message(chat_id: int, message: str) -> str:
"""
 Send a message to a specific chat.
 Args:
 chat_id: The ID of the chat.
 message: The message content to send.
 """
try:
entity = await client.get_entity(chat_id)
await client.send_message(entity, message)
return "Message sent successfully."
except Exception as e:
logger.exception(f"send_message failed (chat_id={chat_id})")
return "An error occurred (code: SENDMSG-ERR-001). Check mcp_errors.log for details."</pre></div>
Example output:
<pre><code>Message sent successfully.
</code></pre>
<div class="markdown-heading"><h3 class="heading-element">Getting Chat Invite Links</h3><a id="user-content-getting-chat-invite-links" class="anchor" aria-label="Permalink: Getting Chat Invite Links" href="#getting-chat-invite-links"></a></div>
The <code>get_invite_link</code> function is particularly robust with multiple fallback methods:
<div class="highlight highlight-source-python"><pre>@mcp.tool()
async def get_invite_link(chat_id: int) -> str:
"""
 Get the invite link for a group or channel.
 """
try:
entity = await client.get_entity(chat_id)

# Try using ExportChatInviteRequest first
try:
from telethon.tl import functions
result = await client(functions.messages.ExportChatInviteRequest(
peer=entity
))
return result.link
except AttributeError:
# If the function doesn't exist in the current Telethon version
logger.warning("ExportChatInviteRequest not available, using alternative method")
except Exception as e1:
# If that fails, log and try alternative approach
logger.warning(f"ExportChatInviteRequest failed: {e1}")

# Alternative approach using client.export_chat_invite_link
try:
invite_link = await client.export_chat_invite_link(entity)
return invite_link
except Exception as e2:
logger.warning(f"export_chat_invite_link failed: {e2}")

# Last resort: Try directly fetching chat info
try:
if isinstance(entity, (Chat, Channel)):
full_chat = await client(functions.messages.GetFullChatRequest(
chat_id=entity.id
))
if hasattr(full_chat, 'full_chat') and hasattr(full_chat.full_chat, 'invite_link'):
return full_chat.full_chat.invite_link or "No invite link available."
except Exception as e3:
logger.warning(f"GetFullChatRequest failed: {e3}")

return "Could not retrieve invite link for this chat."
except Exception as e:
logger.exception(f"get_invite_link failed (chat_id={chat_id})")
return f"Error getting invite link: {e}"</pre></div>
Example output:
<pre><code>https://t.me/+AbCdEfGhIjKlMnOp
</code></pre>
<div class="markdown-heading"><h3 class="heading-element">Joining Chats via Invite Links</h3><a id="user-content-joining-chats-via-invite-links" class="anchor" aria-label="Permalink: Joining Chats via Invite Links" href="#joining-chats-via-invite-links"></a></div>
<div class="highlight highlight-source-python"><pre>@mcp.tool()
async def join_chat_by_link(link: str) -> str:
"""
 Join a chat by invite link.
 """
try:
# Extract the hash from the invite link
if '/' in link:
hash_part = link.split('/')[-1]
if hash_part.startswith('+'):
hash_part = hash_part[1:] # Remove the '+' if present
else:
hash_part = link

# Try checking the invite before joining
try:
# Try to check invite info first (will often fail if not a member)
invite_info = await client(functions.messages.CheckChatInviteRequest(hash=hash_part))
if hasattr(invite_info, 'chat') and invite_info.chat:
# If we got chat info, we're already a member
chat_title = getattr(invite_info.chat, 'title', 'Unknown Chat')
return f"You are already a member of this chat: {chat_title}"
except Exception:
# This often fails if not a member - just continue
pass

# Join the chat using the hash
result = await client(functions.messages.ImportChatInviteRequest(hash=hash_part))
if result and hasattr(result, 'chats') and result.chats:
chat_title = getattr(result.chats[0], 'title', 'Unknown Chat')
return f"Successfully joined chat: {chat_title}"
return f"Joined chat via invite hash."
except Exception as e:
err_str = str(e).lower()
if "expired" in err_str:
return "The invite hash has expired and is no longer valid."
elif "invalid" in err_str:
return "The invite hash is invalid or malformed."
elif "already" in err_str and "participant" in err_str:
return "You are already a member of this chat."
logger.exception(f"join_chat_by_link failed (link={link})")
return f"Error joining chat: {e}"</pre></div>
Example output:
<pre><code>Successfully joined chat: Developer Community
</code></pre>
<div class="markdown-heading"><h3 class="heading-element">Searching Public Chats</h3><a id="user-content-searching-public-chats" class="anchor" aria-label="Permalink: Searching Public Chats" href="#searching-public-chats"></a></div>
<div class="highlight highlight-source-python"><pre>@mcp.tool()
async def search_public_chats(query: str) -> str:
"""
 Search for public chats, channels, or bots by username or title.
 """
try:
result = await client(functions.contacts.SearchRequest(q=query, limit=20))
return json.dumps([format_entity(u) for u in result.users], indent=2)
except Exception as e:
return f"Error searching public chats: {e}"</pre></div>
Example output:
<div class="highlight highlight-source-json"><pre>[
{
"id": 123456789,
"name": "TelegramBot",
"type": "user",
"username": "telegram_bot"
},
{
"id": 987654321,
"name": "Telegram News",
"type": "user",
"username": "telegram_news"
}
]</pre></div>
<div class="markdown-heading"><h3 class="heading-element">Getting Direct Chats with Contacts</h3><a id="user-content-getting-direct-chats-with-contacts" class="anchor" aria-label="Permalink: Getting Direct Chats with Contacts" href="#getting-direct-chats-with-contacts"></a></div>
<div class="highlight highlight-source-python"><pre>@mcp.tool()
async def get_direct_chat_by_contact(contact_query: str) -> str:
"""
 Find a direct chat with a specific contact by name, username, or phone.
 
 Args:
 contact_query: Name, username, or phone number to search for.
 """
try:
# Fetch all contacts using the correct Telethon method
result = await client(functions.contacts.GetContactsRequest(hash=0))
contacts = result.users
found_contacts = []
for contact in contacts:
if not contact:
continue
name = f"{getattr(contact, 'first_name', '')} {getattr(contact, 'last_name', '')}".strip()
username = getattr(contact, 'username', '')
phone = getattr(contact, 'phone', '')
if (contact_query.lower() in name.lower() or
(username and contact_query.lower() in username.lower()) or
(phone and contact_query in phone)):
found_contacts.append(contact)
if not found_contacts:
return f"No contacts found matching '{contact_query}'."
# If we found contacts, look for direct chats with them
results = []
dialogs = await client.get_dialogs()
for contact in found_contacts:
contact_name = f"{getattr(contact, 'first_name', '')} {getattr(contact, 'last_name', '')}".strip()
for dialog in dialogs:
if isinstance(dialog.entity, User) and dialog.entity.id == contact.id:
chat_info = f"Chat ID: {dialog.entity.id}, Contact: {contact_name}"
if getattr(contact, 'username', ''):
chat_info += f", Username: @{contact.username}"
if dialog.unread_count:
chat_info += f", Unread: {dialog.unread_count}"
results.append(chat_info)
break

if not results:
return f"Found contacts matching '{contact_query}', but no direct chats with them."

return "\n".join(results)
except Exception as e:
return f"Error searching for direct chat: {e}"</pre></div>
Example output:
<pre><code>Chat ID: 123456789, Contact: John Smith, Username: @johnsmith, Unread: 3
</code></pre>
<hr>
<div class="markdown-heading"><h2 class="heading-element">🎮 Usage Examples</h2><a id="user-content--usage-examples" class="anchor" aria-label="Permalink: 🎮 Usage Examples" href="#-usage-examples"></a></div>
<ul>
<li>"Show my recent chats"</li>
<li>"Send 'Hello world' to chat 123456789"</li>
<li>"Add contact with phone +1234567890, name John Doe"</li>
<li>"Create a group 'Project Team' with users 111, 222, 333"</li>
<li>"Download the media from message 42 in chat 123456789"</li>
<li>"Mute notifications for chat 123456789"</li>
<li>"Promote user 111 to admin in group 123456789"</li>
<li>"Search for public channels about 'news'"</li>
<li>"Join the Telegram group with invite link <a href="https://t.me/+AbCdEfGhIjK" rel="nofollow">https://t.me/+AbCdEfGhIjK</a>"</li>
<li>"Send a sticker to my Saved Messages"</li>
<li>"Get all my sticker sets"</li>
</ul>
You can use these tools via natural language in Claude, Cursor, or any MCP-compatible client.
<hr>
<div class="markdown-heading"><h2 class="heading-element">🧠 Error Handling & Robustness</h2><a id="user-content--error-handling--robustness" class="anchor" aria-label="Permalink: 🧠 Error Handling & Robustness" href="#-error-handling--robustness"></a></div>
This implementation includes comprehensive error handling:
<ul>
<li>
Session management: Works with both file-based and string-based sessions</li>
<li>
Error reporting: Detailed errors logged to <code>mcp_errors.log</code>
</li>
<li>
Graceful degradation: Multiple fallback approaches for critical functions</li>
<li>
User-friendly messages: Clear, actionable error messages instead of technical errors</li>
<li>
Account type detection: Functions that require bot accounts detect and notify when used with user accounts</li>
<li>
Invite link processing: Handles various link formats and already-member cases</li>
</ul>
The code is designed to be robust against common Telegram API issues and limitations.
<hr>
<div class="markdown-heading"><h2 class="heading-element">🛠️ Contribution Guide</h2><a id="user-content-️-contribution-guide" class="anchor" aria-label="Permalink: 🛠️ Contribution Guide" href="#️-contribution-guide"></a></div>
<ol>
<li>
Fork this repo: <a href="https://github.com/chigwell/telegram-mcp">chigwell/telegram-mcp</a>
</li>
<li>
Clone your fork:
<div class="highlight highlight-source-shell"><pre>git clone https://github.com/<your-github-username>/telegram-mcp.git</pre></div>
</li>
<li>
Create a new branch:
<div class="highlight highlight-source-shell"><pre>git checkout -b my-feature</pre></div>
</li>
<li>Make your changes, add tests/docs if needed.</li>
<li>
Push and open a Pull Request to <a href="https://github.com/chigwell/telegram-mcp">chigwell/telegram-mcp</a> with a clear description.</li>
<li>
Tag @chigwell or @l1v0n1 in your PR for review.</li>
</ol>
<hr>
<div class="markdown-heading"><h2 class="heading-element">🔒 Security Considerations</h2><a id="user-content--security-considerations" class="anchor" aria-label="Permalink: 🔒 Security Considerations" href="#-security-considerations"></a></div>
<ul>
<li>Never commit your <code>.env</code> or session string.</li>
<li>The session string gives full access to your Telegram account—keep it safe!</li>
<li>All processing is local; no data is sent anywhere except Telegram's API.</li>
<li>Use <code>.env.example</code> as a template and keep your actual <code>.env</code> file private.</li>
<li>Test files are automatically excluded in <code>.gitignore</code>.</li>
</ul>
<hr>
<div class="markdown-heading"><h2 class="heading-element">🛠️ Troubleshooting</h2><a id="user-content-️-troubleshooting" class="anchor" aria-label="Permalink: 🛠️ Troubleshooting" href="#️-troubleshooting"></a></div>
<ul>
<li>
Check logs in your MCP client (Claude/Cursor) and the terminal for errors.</li>
<li>
Detailed error logs can be found in <code>mcp_errors.log</code>.</li>
<li>
Interpreter errors? Make sure your <code>.venv</code> is created and selected.</li>
<li>
Database lock? Use session string authentication, not file-based sessions.</li>
<li>
iCloud/Dropbox issues? Move your project to a local path without spaces if you see odd errors.</li>
<li>
Regenerate session string if you change your Telegram password or see auth errors.</li>
<li>
Bot-only functions will show clear messages when used with regular user accounts.</li>
<li>
Test script failures? Check test configuration in <code>.env</code> for valid test accounts/groups.</li>
</ul>
<hr>
<div class="markdown-heading"><h2 class="heading-element">📄 License</h2><a id="user-content--license" class="anchor" aria-label="Permalink: 📄 License" href="#-license"></a></div>
This project is licensed under the <a href="LICENSE">Apache 2.0 License</a>.
<hr>
<div class="markdown-heading"><h2 class="heading-element">🙏 Acknowledgements</h2><a id="user-content--acknowledgements" class="anchor" aria-label="Permalink: 🙏 Acknowledgements" href="#-acknowledgements"></a></div>
<ul>
<li><a href="https://github.com/LonamiWebs/Telethon">Telethon</a></li>
<li><a href="https://modelcontextprotocol.io/" rel="nofollow">Model Context Protocol</a></li>
<li>
<a href="https://www.anthropic.com/" rel="nofollow">Claude</a> and <a href="https://cursor.so/" rel="nofollow">Cursor</a>
</li>
<li>
<a href="https://github.com/chigwell/telegram-mcp">chigwell/telegram-mcp</a> (upstream)</li>
</ul>
<hr>
Maintained by <a href="https://github.com/chigwell">@chigwell</a> and <a href="https://github.com/l1v0n1">@l1v0n1</a>. PRs welcome!
<div class="markdown-heading"><h2 class="heading-element">Star History</h2><a id="user-content-star-history" class="anchor" aria-label="Permalink: Star History" href="#star-history"></a></div>
<a href="https://www.star-history.com/#chigwell/telegram-mcp&Date" rel="nofollow"><img src="https://camo.githubusercontent.com/306fadc6b980dfe16effdfbc9a919120fd79…; alt="Star History Chart" data-canonical-src="https://api.star-history.com/svg?repos=chigwell/telegram-mcp&type=D…; style="max-width: 100%;"></a>

Learn more

Browse by Category

Explore pre-built MCP servers for popular enterprise systems that connect AI assistants to your data sources.

Aggregators

Servers for accessing many apps and tools through a single MCP server.

Art & Culture

Access and explore art collections, cultural heritage, and museum databases. Enables AI models to search and analyze artistic and cultural content.

Browser Automation

Web content access and automation capabilities. Enables searching, scraping, and processing web content in AI-friendly formats.

Biology, Medicine and Bioinformatics

Cloud Platforms

Cloud platform service integration. Enables management and interaction with cloud infrastructure and services.

Code Execution

Code execution servers. Allow LLMs to execute code in a secure environment, e.g. for coding agents.

Coding Agents

Full coding agents that enable LLMs to read, edit, and execute code and solve general programming tasks completely autonomously.

Command Line

Run commands, capture output and otherwise interact with shells and command line tools.

Get Started with MCP

Begin building and testing MCP connectors today to enhance your AI applications with context-aware capabilities.

Join the Community

Contribute to our open-source repositories and implementations.

Build Your First Server

Follow our quickstart guide to build a custom MCP server.

Install Pre-built Servers

Get started quickly with pre-built MCP servers for popular systems.

Key Benefits

The Model Context Protocol provides a simpler, more reliable way to give AI systems access to the data they need.

Secure Integration

Build secure, two-way connections between your data sources and AI-powered tools with controlled access.

Universal Connectivity

Replace fragmented integrations with a single protocol that connects to multiple data sources.

Context-Aware AI

Enable AI assistants to access relevant information from your systems to produce better, more accurate responses.

Model Context Protocol

AI Assistants

Data Sources

Development Tools

Open Standard