Telegram MCP

🚀 Telegram MCP English Documentation

This project offers a comprehensive set of tools for interacting with Telegram, enabling users to perform various operations such as sending messages, managing contacts, and handling media files.

✨ Features

🔧 Tool List

1. Display recent chat history
2. Send messages to a specified chat
3. Add contacts (including name and phone number)
4. Create groups (specify group name and member IDs)
5. Download media files (download images, videos, etc. from specified messages)
6. Mute notifications (set mute or do-not-disturb mode for specific chats)
7. Elevate user permissions (set a user as an administrator in a group)
8. Search for public channels/groups
9. Join Telegram groups (via invitation link)
10. Send messages to "Saved Messages"
11. Get sticker packs for all chats

🛠️ Core Features

• Supports file and string sessions, suitable for different environments.
• Detailed error logging for easy troubleshooting.
• Multiple functional mode switches to ensure stable operation.
• User-friendly prompt messages to enhance the user experience.

🚀 Quick Start

🎮 Installation and Configuration

1. Clone the repository

   git clone https://github.com/chigwell/telegram-mcp.git
   

2. Install dependencies

   pip install telethon mcprompto
   

3. Create a configuration file
   • Copy config.example.yaml to config.yaml.
   • Fill in your Telegram API token and MCP client configuration.

🏷️ Label Management

• Add a label: add_label.yml
• Delete a label: remove_label.yml
• List all labels: list_labels.yml

📋 Environment Variable Settings

💻 Usage Examples

Sending Messages

# Send a text message
tasks:
  - send_message:
      chat_id: "123456789"
      text: "Hello, World!"
      message_thread_id: 0

# Send a photo message
tasks:
  - send_photo:
      chat_id: "123456789"
      photo_path: "./image.jpg"

# Send a file
tasks:
  - send_document:
      chat_id: "123456789"
      document_path: "./file.txt"

Group Management

# Create a group
tasks:
  - create_group:
      group_name: "Project Team"
      user_ids: [111, 222, 333]

# Add a member
tasks:
  - add_user_to_group:
      chat_id: "123456789"
      user_id: 444

# Delete a group
tasks:
  - delete_group:
      chat_id: "123456789"

Message Operations

# Get message history
tasks:
  - get_message_history:
      chat_id: "123456789"
      limit: 10

# Delete a specified message
tasks:
  - delete_message:
      chat_id: "123456789"
      message_id: 42

📜 Example Conversations

• "Show my recent chats"
• "Send 'Hello world' to 123456789"
• "Add a contact with phone number +1234567890 and name John Doe"
• "Create a group named 'Project Team' with users 111, 222, 333"
• "Download the media file from message 42 in chat 123456789"
• "Mute chat 123456789"
• "Promote user 111 to administrator in group 123456789"
• "Search for public channels/groups about 'news'"
• "Join a Telegram group via invitation link https://t.me/+AbCdEfGhIjK"
• "Send a message to Saved Messages"
• "Get sticker packs for all chats"

📚 Advanced Guide

Session Management

1. File session: Place session.json in the project root directory.
2. String session: Set SESSION_STRING through environment variables.

Network Configuration

• Proxy settings:

  proxies:
    http: "http://proxy.example.com:8080"
    https: "https://proxy.example.com:8443"
  

⚠️ Security Precautions

1. Key protection: Avoid committing API keys to version control.
2. Permission management: Set bot permissions reasonably to prevent unauthorized operations.

📦 Release Notes

v0.5

• Added group management features
• Optimized message sending performance
• Fixed some boundary condition issues

🔧 Troubleshooting

1. Cannot connect to Telegram:

   • Check network configuration
   • Ensure API keys are valid

2. Insufficient permissions:

   • Verify bot permission settings
   • Elevate administrator permissions for the target chat

3. Error logs:

   • Check the error.log file
   • Refer to Common Issues