TGMCP - Telegram Model Context Protocol

Connect AI agents with Telegram using MCP standard

📖 Overview

TGMCP is a Python package that implements the Model Context Protocol (MCP) for Telegram. It allows AI agents to seamlessly interact with Telegram accounts, providing access to messaging, contacts, groups, media sharing, and more.

This package acts as a bridge between AI assistants and Telegram, enabling them to:

• Read and send messages
• Manage contacts and groups
• Handle media (images, documents, stickers, GIFs)
• Perform administrative functions
• Update profile information

All data is handled locally and securely through the Telegram API.

✨ Key Features

• Chat Operations: List chats, retrieve messages, send messages
• Contact Management: Add, delete, block/unblock, search contacts
• Group Administration: Create groups, add members, manage permissions
• Media Handling: Send/receive files, stickers, GIFs, voice messages
• Profile Management: Update profile info, privacy settings
• Message Operations: Forward, edit, delete, pin messages
• Administrative Functions: Promote/demote admins, ban users

🚀 Installation

From PyPI (Recommended)

pip install tgmcp

From Source

# Clone the repository
git clone https://github.com/OEvortex/tgmcp.git
cd tgmcp

# Install with pip
pip install -e .

⚙️ Configuration

Environment Variables

Create a .env file in your project directory with your Telegram API credentials:

TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
TELEGRAM_SESSION_NAME=your_session_name
# Optional: Use string session instead of file session
# TELEGRAM_SESSION_STRING=your_session_string

# Optional: Tool Configuration
# Control which tool sets are enabled (default is true for all)
# TGMCP_ENABLE_CHAT_TOOLS=true
# TGMCP_ENABLE_CONTACT_TOOLS=true
# TGMCP_ENABLE_MESSAGE_TOOLS=true
# TGMCP_ENABLE_GROUP_TOOLS=true
# TGMCP_ENABLE_MEDIA_TOOLS=true
# TGMCP_ENABLE_PROFILE_TOOLS=true
# TGMCP_ENABLE_ADMIN_TOOLS=true

MCP Configuration

To use TGMCP with VS Code or other MCP-compatible applications, add it to your MCP configuration:

Option 1: Using Session String (Recommended)

{
  "mcp": {
    "servers": {
      "mcp-telegram": {
        "command": "tgmcp",
        "args": ["start"],
        "env": {
          "TELEGRAM_API_ID": "your_api_id",
          "TELEGRAM_API_HASH": "your_api_hash",
          "TELEGRAM_SESSION_STRING": "your_session_string",
          "MCP_NONINTERACTIVE": "true",
          
          "TGMCP_ENABLE_CHAT_TOOLS": "true",
          "TGMCP_ENABLE_CONTACT_TOOLS": "true",
          "TGMCP_ENABLE_MESSAGE_TOOLS": "true",
          "TGMCP_ENABLE_GROUP_TOOLS": "true",
          "TGMCP_ENABLE_MEDIA_TOOLS": "true",
          "TGMCP_ENABLE_PROFILE_TOOLS": "true",
          "TGMCP_ENABLE_ADMIN_TOOLS": "true"
        }
      }
    }
  }
}

IMPORTANT:

1. Replace your_api_id, your_api_hash, and your_session_string with your actual Telegram API credentials.
2. For most reliable operation, use the session string method (Option 1).
3. The MCP_NONINTERACTIVE setting prevents interactive prompts during startup.

Option 2: Using Session Files (Basic Method)

{
  "mcp": {
    "servers": {
      "mcp-telegram": {
        "command": "tgmcp",
        "args": ["start"],
        "env": {
          "TELEGRAM_API_ID": "your_api_id",
          "TELEGRAM_API_HASH": "your_api_hash",
          "TELEGRAM_SESSION_NAME": "your_session_name",
          "MCP_NONINTERACTIVE": "true",
          
          "TGMCP_ENABLE_CHAT_TOOLS": "true",
          "TGMCP_ENABLE_CONTACT_TOOLS": "true",
          "TGMCP_ENABLE_MESSAGE_TOOLS": "true",
          "TGMCP_ENABLE_GROUP_TOOLS": "true",
          "TGMCP_ENABLE_MEDIA_TOOLS": "true",
          "TGMCP_ENABLE_PROFILE_TOOLS": "true",
          "TGMCP_ENABLE_ADMIN_TOOLS": "true"
        }
      }
    }
  }
}

Tool Configuration

TGMCP allows you to selectively enable or disable specific tool sets using environment variables. This can be useful for:

• Reducing the number of available tools for security or simplicity
• Limiting functionality for specific use cases
• Improving performance by loading only necessary components

You can configure which tool sets are enabled by setting the following environment variables:

Environment Variable	Description	Default
TGMCP_ENABLE_CHAT_TOOLS	Enable/disable chat-related tools	true
TGMCP_ENABLE_CONTACT_TOOLS	Enable/disable contact management tools	true
TGMCP_ENABLE_MESSAGE_TOOLS	Enable/disable message operation tools	true
TGMCP_ENABLE_GROUP_TOOLS	Enable/disable group administration tools	true
TGMCP_ENABLE_MEDIA_TOOLS	Enable/disable media handling tools	true
TGMCP_ENABLE_PROFILE_TOOLS	Enable/disable profile management tools	true
TGMCP_ENABLE_ADMIN_TOOLS	Enable/disable administrative function tools	true

Set these variables to true or false to enable or disable the corresponding tool set. For example:

# Disable admin and group tools, enable everything else
TGMCP_ENABLE_ADMIN_TOOLS=false
TGMCP_ENABLE_GROUP_TOOLS=false

First-Time Authentication

Before using TGMCP, you need to authenticate with Telegram. You can do this in two ways:

Option 1: Generate a Session String (Recommended)

# Run the session string generator
python -m tgmcp.session_string_generator

This will generate a session string that you can use in your MCP configuration. This method is more reliable and portable, especially for cloud environments.

Option 2: Use File-Based Authentication

# Run the authentication script
python -m tgmcp.authenticate

This will create a .session file that TGMCP will use for authentication.

🔍 Usage

Run as MCP Server

python -m tgmcp

Use in Your Code

import asyncio
import os
from tgmcp import client, get_tool_config

async def main():
    # Optional: Configure which tools to enable
    # These should be set before importing any tools
    os.environ["TGMCP_ENABLE_ADMIN_TOOLS"] = "false"  # Disable admin tools
    
    # Connect to Telegram
    await client.start()
    
    # Get user info
    me = await client.get_me()
    print(f"Logged in as: {me.first_name} {getattr(me, 'last_name', '')}")
    
    # Send a message
    await client.send_message('username', 'Hello from TGMCP!')
    
    # Check which tool sets are enabled
    tool_config = get_tool_config()
    print("Enabled tool sets:", [k for k, v in tool_config.items() if v])
    
    # Disconnect when done
    await client.disconnect()

asyncio.run(main())

🛠️ Available MCP Tools

TGMCP provides a comprehensive set of tools that can be utilized through the MCP protocol:

Chat Tools

• get_chats - List available chats with pagination
• list_chats - Detailed metadata for users, groups, and channels
• get_chat - Information about a specific chat
• get_direct_chat_by_contact - Find a direct chat with a specific contact
• send_message - Send text messages to any chat
• archive_chat - Archive a chat
• unarchive_chat - Unarchive a chat
• mute_chat - Mute notifications for a chat
• unmute_chat - Unmute notifications for a chat
• get_invite_link - Get the invite link for a group or channel
• export_chat_invite - Export a chat invite link
• join_chat_by_link - Join a chat by invite link
• import_chat_invite - Import a chat invite by hash

Message Operations

• get_messages - Get paginated messages from a specific chat
• list_messages - List messages with detailed information
• get_message_context - Get context around a specific message
• forward_message - Forward a message to another chat
• edit_message - Edit a previously sent message
• delete_message - Delete messages
• pin_message - Pin a message in a chat
• unpin_message - Unpin a message from a chat
• mark_as_read - Mark messages as read
• reply_to_message - Reply to a specific message
• search_messages - Search for messages in a chat
• get_pinned_messages - Get all pinned messages in a chat
• get_history - Get chat history with customizable filters

Contact Management

• list_contacts - View all contacts in your Telegram account
• search_contacts - Find contacts by name, username, or phone
• get_contact_ids - Get contact IDs for specific contacts
• get_contact_chats - Get chats with specific contacts
• get_last_interaction - Get last interaction with a contact
• add_contact - Add new contacts to your Telegram account
• delete_contact - Delete contacts from your account
• block_user - Block users from contacting you
• unblock_user - Unblock previously blocked users
• import_contacts - Import multiple contacts at once
• export_contacts - Export all contacts to a structured format
• get_blocked_users - Get a list of blocked users
• resolve_username - Resolve a username to a Telegram entity
• search_public_chats - Search for public chats

Group Administration

• create_group - Create new groups and add members
• create_channel - Create a new broadcast channel
• invite_to_group - Invite users to existing groups
• leave_chat - Leave a group or channel
• get_participants - List members of a group or channel
• edit_chat_title - Change the title of a group or channel
• edit_chat_photo - Change the photo of a group or channel
• delete_chat_photo - Remove the photo from a group or channel
• promote_admin - Give administrator privileges to users
• demote_admin - Revoke administrator privileges
• ban_user - Ban users from a group or channel
• unban_user - Unban previously banned users
• get_admins - List administrators of a group or channel
• get_banned_users - List banned users
• get_recent_actions - Get recent administrative actions

Media Tools

• send_file - Send documents, photos, or videos
• download_media - Save media from messages to your device
• get_media_info - Get information about media in messages
• send_voice - Send voice messages
• send_sticker - Send stickers to chats
• get_sticker_sets - Get available sticker sets
• get_gif_search - Search for GIFs
• send_gif - Send GIFs to chats

Profile Management

• get_me - Get information about your own account
• update_profile - Update profile information (name, bio)
• set_profile_photo - Set a new profile photo
• delete_profile_photo - Remove profile photos
• get_privacy_settings - Get current privacy settings
• set_privacy_settings - Update privacy settings
• get_user_photos - Get a user's profile photos
• get_user_status - Check a user's online status
• get_bot_info - Get information about a bot
• set_bot_commands - Configure bot commands

📚 Example

import asyncio
import os
from dotenv import load_dotenv
from tgmcp import client, get_tool_config

# Load environment variables
load_dotenv()

# Optional: Configure which tools to enable
# os.environ["TGMCP_ENABLE_ADMIN_TOOLS"] = "false"  # Uncomment to disable admin tools

async def example():
    # Start the client
    await client.start()
    
    # Get recent chats
    dialogs = await client.get_dialogs(limit=5)
    print("\nRecent chats:")
    for dialog in dialogs:
        chat_name = getattr(dialog.entity, "title", None) or getattr(dialog.entity, "first_name", "Unknown")
        print(f"- {chat_name} (ID: {dialog.entity.id})")
    
    # Display which tool sets are enabled
    tool_config = get_tool_config()
    print("\nEnabled tool sets:")
    for tool_set, enabled in tool_config.items():
        status = "✅ Enabled" if enabled else "❌ Disabled"
        print(f"- {tool_set}: {status}")
    
    # Disconnect when done
    await client.disconnect()

if __name__ == "__main__":
    asyncio.run(example())

🔒 Security & Privacy

• All data remains on your local machine
• Authentication with Telegram is handled securely
• No data is sent to third parties
• Session files should be kept secure

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

📄 License

MIT License

📞 Support

For issues and questions, please open an issue on the GitHub repository.

📦 PyPI Package

This package is available on PyPI:

• https://pypi.org/project/tgmcp/

You can install it using pip:

pip install tgmcp

---

Made with ❤️ for AI-assisted Telegram interaction