Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/oevortex/tgmcp

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.
https://github.com/oevortex/tgmcp

ai-agents claude mcp-servers model-context-protocol-servers telegram-api telegram-api-bot

Last synced: 3 months ago
JSON representation

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.

Awesome Lists containing this project

README 

          
# TGMCP - Telegram Model Context Protocol





  Telegram Logo

  


  Connect AI agents with Telegram using MCP standard

  



  

    PyPI version

  

  

    License

  

  

    MCP Protocol

  

  

    Ask DeepWiki

  




## 📖 Overview



TGMCP is a Python package that implements the [Model Context Protocol (MCP)](https://github.com/anthropics/anthropic-cookbook/tree/main/model_context_protocol) 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)

```bash

pip install tgmcp

```



### From Source

```bash

# 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)

```json

{

  "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)

```json

{

  "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)

```bash

# 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

```bash

# 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

```bash

python -m tgmcp

```



### Use in Your Code

```python

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



```python

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](LICENSE)



## 📞 Support



For issues and questions, please open an issue on the [GitHub repository](https://github.com/OEvortex/tgmcp/issues).



## 📦 PyPI Package



This package is available on PyPI:

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



You can install it using pip:

```bash

pip install tgmcp

```



---





  
Made with ❤️ for AI-assisted Telegram interaction