Telegram Integration MCP Server

CommunicationPython

Interact with your Telegram account programmatically through Claude and other MCP clients

Available Tools

get_me

Get information about the current user account

get_chats

Retrieve a list of all chats (dialogs)

get_chat_by_id

Get information about a specific chat by its ID

get_chat_by_username

Get information about a specific chat by its username

get_messages

Retrieve messages from a specific chat

send_message

Send a message to a specific chat

search_contacts

Search for contacts by name or username

get_message_context

Get context around a specific message

create_group

Create a new group chat

add_user_to_group

Add a user to a group chat

remove_user_from_group

Remove a user from a group chat

get_group_members

Get a list of members in a group chat

A comprehensive Telegram integration that allows AI assistants to interact with your Telegram account through the Model Context Protocol. Powered by Telethon, this integration enables seamless access to your chats, contacts, and messages, while providing powerful automation capabilities for messaging and group management. With this MCP server, AI assistants can retrieve chat history, send messages, manage groups, search for contacts, and perform virtually any action available in the Telegram API. The integration is designed to be secure, efficient, and compatible with Claude, Cursor, and any other MCP-compatible client.

Installation

Prerequisites

Python 3.10 or higher
Telegram API credentials (API ID and API Hash)
A Telegram account

Setup Instructions

Clone the repository:

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

Set up environment variables: Create a .env file based on the provided .env.example:
```
API_ID=your_telegram_api_id
API_HASH=your_telegram_api_hash
SESSION_STRING=optional_session_string
MCP_PORT=8000
```
You can obtain your API ID and API Hash from my.telegram.org.
Generate a session string (optional but recommended):
```
python session_string_generator.py
```
Follow the prompts to log in to your Telegram account and generate a session string. Add this string to your .env file.

Install dependencies: Using Poetry:

poetry install

Or using pip:

pip install -r requirements.txt

Run the MCP server:
```
python main.py
```
The server will start on the port specified in your .env file (default: 8000).

Docker Installation

Alternatively, you can use Docker Compose:

Create your .env file as described above.
Run:
```
docker-compose up -d
```

Usage

Once the server is running, you can connect to it from any MCP-compatible client like Claude or Cursor.

Security Considerations

The session string grants access to your Telegram account, so keep it secure.
Consider using a separate Telegram account for testing or automation purposes.
Be mindful of Telegram's rate limits to avoid getting your account temporarily banned.

Example Interactions

You can ask your AI assistant to:

Retrieve messages from a specific chat: "Show me the last 10 messages from my chat with John."
Send a message: "Send a message to the 'Project Team' group saying 'The meeting is postponed to tomorrow at 3 PM.'"
Search for contacts: "Find all contacts with 'Smith' in their name."
Analyze chat history: "Summarize the conversation in my 'Family' group from yesterday."
Manage groups: "Add user @username to my 'Tech Discussion' group."

The MCP server handles these requests by translating them into appropriate Telegram API calls through the Telethon library.