Integrations
Enables interaction with Telegram chats, allowing users to retrieve lists of chats, fetch message history, and send messages directly through the Telegram platform.
Telegram MCP Server
🤖 MCP in Action
Here's a demonstration of the Telegram MCP capabilities in Claude:
Basic usage example:
- Example: Asking Claude to analyze chat history and send a response:
- Successfully sent message to the group:
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.
A full-featured Telegram integration for Claude, Cursor, and any MCP-compatible client, powered by Telethon and the Model Context Protocol (MCP). This project lets you interact with your Telegram account programmatically, automating everything from messaging to group management.
🚀 Features & Tools
This MCP server exposes a huge suite of Telegram tools. Every major Telegram/Telethon feature is available as a tool!
Chat & Group Management
- get_chats(page, page_size): Paginated list of chats
- list_chats(chat_type, limit): List chats with metadata and filtering
- get_chat(chat_id): Detailed info about a chat
- create_group(title, user_ids): Create a new group
- create_channel(title, about, megagroup): Create a channel or supergroup
- edit_chat_title(chat_id, title): Change chat/group/channel title
- delete_chat_photo(chat_id): Remove chat/group/channel photo
- leave_chat(chat_id): Leave a group or channel
- get_participants(chat_id): List all participants
- get_admins(chat_id): List all admins
- get_banned_users(chat_id): List all banned users
- promote_admin(chat_id, user_id): Promote user to admin
- demote_admin(chat_id, user_id): Demote admin to user
- ban_user(chat_id, user_id): Ban user
- unban_user(chat_id, user_id): Unban user
- get_invite_link(chat_id): Get invite link
- export_chat_invite(chat_id): Export invite link
- import_chat_invite(hash): Join chat by invite hash
- join_chat_by_link(link): Join chat by invite link
Messaging
- get_messages(chat_id, page, page_size): Paginated messages
- list_messages(chat_id, limit, search_query, from_date, to_date): Filtered messages
- send_message(chat_id, message): Send a message
- reply_to_message(chat_id, message_id, text): Reply to a message
- edit_message(chat_id, message_id, new_text): Edit your message
- delete_message(chat_id, message_id): Delete a message
- forward_message(from_chat_id, message_id, to_chat_id): Forward a message
- pin_message(chat_id, message_id): Pin a message
- unpin_message(chat_id, message_id): Unpin a message
- mark_as_read(chat_id): Mark all as read
- get_message_context(chat_id, message_id, context_size): Context around a message
- get_history(chat_id, limit): Full chat history
- get_pinned_messages(chat_id): List pinned messages
- get_last_interaction(contact_id): Most recent message with a contact
Contact Management
- list_contacts(): List all contacts
- search_contacts(query): Search contacts
- add_contact(phone, first_name, last_name): Add a contact
- delete_contact(user_id): Delete a contact
- block_user(user_id): Block a user
- unblock_user(user_id): Unblock a user
- import_contacts(contacts): Bulk import contacts
- export_contacts(): Export all contacts as JSON
- get_blocked_users(): List blocked users
- get_contact_ids(): List all contact IDs
- get_direct_chat_by_contact(contact_query): Find direct chat with a contact
- get_contact_chats(contact_id): List all chats with a contact
User & Profile
- get_me(): Get your user info
- update_profile(first_name, last_name, about): Update your profile
- delete_profile_photo(): Remove your profile photo
- get_user_photos(user_id, limit): Get a user's profile photos
- get_user_status(user_id): Get a user's online status
Media
- get_media_info(chat_id, message_id): Get info about media in a message
Search & Discovery
- search_public_chats(query): Search public chats/channels/bots
- search_messages(chat_id, query, limit): Search messages in a chat
- resolve_username(username): Resolve a username to ID
Stickers, GIFs, Bots
- get_sticker_sets(): List sticker sets
- get_bot_info(bot_username): Get info about a bot
- set_bot_commands(bot_username, commands): Set bot commands (bot accounts only)
Privacy, Settings, and Misc
- get_privacy_settings(): Get privacy settings
- set_privacy_settings(key, allow_users, disallow_users): Set privacy settings
- mute_chat(chat_id): Mute notifications
- unmute_chat(chat_id): Unmute notifications
- archive_chat(chat_id): Archive a chat
- unarchive_chat(chat_id): Unarchive a chat
- get_recent_actions(chat_id): Get recent admin actions
Removed Functionality
Please note that tools requiring direct file path access on the server (send_file
, download_media
, set_profile_photo
, edit_chat_photo
, send_voice
, send_sticker
, upload_file
) have been removed from main.py
. This is due to limitations in the current MCP environment regarding handling file attachments and local file system paths.
Additionally, GIF-related tools (get_gif_search
, get_saved_gifs
, send_gif
) have been removed due to ongoing issues with reliability in the Telethon library or Telegram API interactions.
📋 Requirements
- Python 3.10+
- Telethon
- MCP Python SDK
- Claude Desktop or Cursor (or any MCP client)
🔧 Installation & Setup
1. Fork & Clone
2. Create a Virtual Environment
3. Generate a Session String
Follow the prompts to authenticate and update your .env
file.
4. Configure .env
Copy .env.example
to .env
and fill in your values:
Get your API credentials at my.telegram.org/apps.
🐳 Running with Docker
If you have Docker and Docker Compose installed, you can build and run the server in a container, simplifying dependency management.
1. Build the Image
From the project root directory, build the Docker image:
2. Running the Container
You have two options:
Option A: Using Docker Compose (Recommended for Local Use)
This method uses the docker-compose.yml
file and automatically reads your credentials from a .env
file.
- Create
.env
File: Ensure you have a.env
file in the project root containing yourTELEGRAM_API_ID
,TELEGRAM_API_HASH
, andTELEGRAM_SESSION_STRING
(orTELEGRAM_SESSION_NAME
). Use.env.example
as a template. - Run Compose:Copy
- Use
docker compose up -d
to run in detached mode (background). - Press
Ctrl+C
to stop the server.
- Use
Option B: Using docker run
You can run the container directly, passing credentials as environment variables.
- Replace placeholders with your actual credentials.
- Use
-e TELEGRAM_SESSION_NAME=your_session_file_name
instead ofTELEGRAM_SESSION_STRING
if you prefer file-based sessions (requires volume mounting, seedocker-compose.yml
for an example). - The
-it
flags are crucial for interacting with the server.
⚙️ Configuration for Claude & Cursor
MCP Configuration
Edit your Claude desktop config (e.g. ~/Library/Application Support/Claude/claude_desktop_config.json
) or Cursor config (~/.cursor/mcp.json
):
📝 Tool Examples with Code & Output
Below are examples of the most commonly used tools with their implementation and sample output.
Getting Your Chats
Example output:
Sending Messages
Example output:
Getting Chat Invite Links
The get_invite_link
function is particularly robust with multiple fallback methods:
Example output:
Joining Chats via Invite Links
Example output:
Searching Public Chats
Example output:
Getting Direct Chats with Contacts
Example output:
🎮 Usage Examples
- "Show my recent chats"
- "Send 'Hello world' to chat 123456789"
- "Add contact with phone +1234567890, name John Doe"
- "Create a group 'Project Team' with users 111, 222, 333"
- "Download the media from message 42 in chat 123456789"
- "Mute notifications for chat 123456789"
- "Promote user 111 to admin in group 123456789"
- "Search for public channels about 'news'"
- "Join the Telegram group with invite link https://t.me/+AbCdEfGhIjK"
- "Send a sticker to my Saved Messages"
- "Get all my sticker sets"
You can use these tools via natural language in Claude, Cursor, or any MCP-compatible client.
🧠 Error Handling & Robustness
This implementation includes comprehensive error handling:
- Session management: Works with both file-based and string-based sessions
- Error reporting: Detailed errors logged to
mcp_errors.log
- Graceful degradation: Multiple fallback approaches for critical functions
- User-friendly messages: Clear, actionable error messages instead of technical errors
- Account type detection: Functions that require bot accounts detect and notify when used with user accounts
- Invite link processing: Handles various link formats and already-member cases
The code is designed to be robust against common Telegram API issues and limitations.
🛠️ Contribution Guide
- Fork this repo: chigwell/telegram-mcp
- Clone your fork:Copy
- Create a new branch:Copy
- Make your changes, add tests/docs if needed.
- Push and open a Pull Request to chigwell/telegram-mcp with a clear description.
- Tag @chigwell or @l1v0n1 in your PR for review.
🔒 Security Considerations
- Never commit your
.env
or session string. - The session string gives full access to your Telegram account—keep it safe!
- All processing is local; no data is sent anywhere except Telegram's API.
- Use
.env.example
as a template and keep your actual.env
file private. - Test files are automatically excluded in
.gitignore
.
🛠️ Troubleshooting
- Check logs in your MCP client (Claude/Cursor) and the terminal for errors.
- Detailed error logs can be found in
mcp_errors.log
. - Interpreter errors? Make sure your
.venv
is created and selected. - Database lock? Use session string authentication, not file-based sessions.
- iCloud/Dropbox issues? Move your project to a local path without spaces if you see odd errors.
- Regenerate session string if you change your Telegram password or see auth errors.
- Bot-only functions will show clear messages when used with regular user accounts.
- Test script failures? Check test configuration in
.env
for valid test accounts/groups.
📄 License
This project is licensed under the Apache 2.0 License.
🙏 Acknowledgements
- Telethon
- Model Context Protocol
- Claude and Cursor
- chigwell/telegram-mcp (upstream)
Maintained by @chigwell and @l1v0n1. PRs welcome!
Star History
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
A server that enables interaction with Telegram chats directly through MCP-compatible hosts like Claude for Desktop, providing tools to retrieve chats, get messages, and send messages.
- 🤖 MCP in Action
- 🚀 Features & Tools
- Removed Functionality
- 📋 Requirements
- 🔧 Installation & Setup
- 🐳 Running with Docker
- ⚙️ Configuration for Claude & Cursor
- 📝 Tool Examples with Code & Output
- 🎮 Usage Examples
- 🧠 Error Handling & Robustness
- 🛠️ Contribution Guide
- 🔒 Security Considerations
- 🛠️ Troubleshooting
- 📄 License
- 🙏 Acknowledgements
- Star History
Related MCP Servers
- -securityFlicense-qualityAn MCP server that enables communication with users through Telegram. This server provides a tool to ask questions to users and receive their responses via a Telegram bot.Last updated -116JavaScript
- AsecurityAlicenseAqualityAn MCP server that allows Claude to create, manage and publish X/Twitter posts directly through the chat interface.Last updated -535PythonMIT License
- AsecurityAlicenseAqualityAn MCP server that enables saving and sharing Claude Desktop conversations, allowing users to store chats privately or make them public through a web interface.Last updated -26TypeScriptMIT License
- -securityFlicense-qualityAn MCP server that allows Claude to interact with Discord by providing tools for sending/reading messages and managing server resources through Discord's API.Last updated -JavaScript