tgmcp 0.1.0

Telegram Model Context Protocol integration

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

Prerequisites

• Python 3.8 or higher
• Telegram API credentials (obtain here)
• UV package installer (recommended)

Install with UV (Recommended)

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

# Install with UV
uv pip install -e .

Traditional Install

# 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

MCP Configuration

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

{
  "mcpServers": {
    "mcp-telegram": {
      "command": "tgmcp", /* use full path if client can't find the command (e.g. "/usr/local/bin/tgmcp"). See IMPORTANT section below for full path instructions. */
      "args": ["start"],
      "env": {
        "TELEGRAM_API_ID": "<your_api_id>",
        "TELEGRAM_API_HASH": "<your_api_hash>"
      }
    }
  }
}

IMPORTANT: To find the full path to the tgmcp command:

• Windows: where tgmcp in Command Prompt or Get-Command tgmcp in PowerShell
• macOS/Linux: which tgmcp in Terminal

🔍 Usage

Run as MCP Server

python -m tgmcp

Use in Your Code

import asyncio
from tgmcp import client

async def main():
    # 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!')
    
    # Disconnect when done
    await client.disconnect()

asyncio.run(main())

🛠️ Tools Available

Chat Tools

• get_chats - Get a paginated list of all your Telegram chats
• list_chats - List available chats with detailed metadata (users, groups, channels)
• get_chat - Get detailed information about a specific chat by ID
• get_direct_chat_by_contact - Find direct chats with a specific contact by name/username/phone
• send_message - Send a text message to any chat
• archive_chat - Archive a chat to reduce clutter
• unarchive_chat - Unarchive a previously archived chat
• mute_chat - Mute notifications for a specific chat
• unmute_chat - Unmute previously silenced chat notifications
• get_invite_link - Get an invite link for a group or channel
• export_chat_invite - Create and export a new chat invite link
• join_chat_by_link - Join a chat using an invite link
• import_chat_invite - Import a chat invite by hash code

Contact Tools

• list_contacts - List all contacts in your Telegram account
• search_contacts - Search for contacts by name, username, or phone number
• get_contact_ids - Get all contact IDs in your account
• get_contact_chats - List all chats involving a specific contact
• get_last_interaction - Get the most recent messages with a contact
• add_contact - Add a new contact to your Telegram account
• delete_contact - Delete a contact from your address book
• block_user - Block a user by their user ID
• unblock_user - Unblock a previously blocked user
• import_contacts - Import a list of contacts in batch
• export_contacts - Export all contacts as a JSON string
• get_blocked_users - Get a list of all users you've blocked
• resolve_username - Resolve a username to a user or chat ID
• search_public_chats - Search for public chats, channels, or bots

Message Tools

• get_messages - Get paginated messages from a specific chat
• list_messages - Retrieve messages with optional filters (search, date)
• get_message_context - See messages before and after a specific message
• forward_message - Forward a message from one chat to another
• edit_message - Edit a message you previously sent
• delete_message - Delete a message by ID
• pin_message - Pin an important message in a chat
• unpin_message - Unpin a previously pinned message
• mark_as_read - Mark all messages as read in a chat
• reply_to_message - Reply to a specific message in a chat
• get_history - Get full chat history up to a limit
• search_messages - Search for messages in a chat by text
• get_pinned_messages - Get all pinned messages in a chat

Group & Channel Tools

• create_group - Create a new group and add initial members
• create_channel - Create a new channel or supergroup
• invite_to_group - Invite users to a group or channel
• leave_chat - Leave a group or channel
• get_participants - List all participants in a group or channel
• edit_chat_title - Change the title of a chat, group, or channel
• edit_chat_photo - Change the photo of a chat, group, or channel
• delete_chat_photo - Remove the photo from a chat
• promote_admin - Promote a user to admin with custom rights
• demote_admin - Remove admin status from a user
• ban_user - Ban a user from a group or channel
• unban_user - Unban a previously banned user
• get_admins - Get all admins in a group or channel
• get_banned_users - Get a list of all banned users
• get_recent_actions - View recent admin actions in a group

Media Tools

• send_file - Send any file (document, photo, video) to a chat
• download_media - Download media from a message to local storage
• get_media_info - Get detailed information about media in a message
• send_voice - Send a voice message (OGG/OPUS format)
• send_sticker - Send a sticker to a chat
• get_sticker_sets - Get a list of available sticker sets
• get_gif_search - Search for GIFs by query term
• send_gif - Send a GIF to a chat by its document ID

Profile Tools

• get_me - Get information about your own Telegram user
• update_profile - Update your profile information (name, bio)
• set_profile_photo - Set a new profile photo
• delete_profile_photo - Delete your current profile photo
• get_privacy_settings - View your privacy settings
• set_privacy_settings - Update privacy settings (last seen, phone, etc.)
• get_user_photos - Get profile photos of any user
• get_user_status - Check a user's online status
• get_bot_info - Get information about a bot
• set_bot_commands - Set commands for bots you own

Admin Tools

• promote_admin - Promote a user to admin in a group/channel
• demote_admin - Demote a user from admin status
• ban_user - Ban a user from a group or channel
• unban_user - Unban a previously banned user
• get_admins - Get all admins in a group or channel
• get_banned_users - Get all banned users in a group or channel
• leave_chat - Leave a group or channel
• export_chat_invite - Generate a new invite link
• import_chat_invite - Join a chat using an invite hash
• get_recent_actions - View recent administrative actions

📚 Example

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

# Load environment variables
load_dotenv()

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})")
    
    # 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 GitHub.

---

Made with ❤️ for AI-assisted Telegram interaction