Telegram MCP Server

Connect Claude to your Telegram account to read and send messages.

Features

Available Tools

get_chats - List your Telegram chats
Returns paginated list with chat names, IDs, and unread counts
For page 1, just provide page number
For subsequent pages, use the pagination parameters from the previous response
get_messages - Read messages from a specific chat
Fetches paginated message history
Automatically marks messages as read
mark_messages_read - Mark all unread messages in a chat as read
send_message - Send messages to any chat
Supports replying to specific messages
get_conversation_context - Analyze chat style for natural responses
Reads your conversation style guide from convostyle.txt
Helps Claude match your texting patterns

Setup Guide

Step 1: Get Telegram API Credentials

Go to https://my.telegram.org/apps
Log in and create an application
Save your API ID and API Hash

Step 2: Install

# Clone the repository
git clone https://github.com/alexandertsai/mcp-telegram
cd mcp-telegram

# Set up Python environment
pip install uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync

Step 3: Configure

# Copy the example file
cp .env.example .env

# Edit .env and add your API credentials:
# TELEGRAM_API_ID=your_api_id_here
# TELEGRAM_API_HASH=your_api_hash_here

Step 4: Authenticate

cd src/mcp_telegram
python telethon_auth.py

Follow the prompts: - Enter your phone number (with country code, e.g., +1234567890) - Enter the code sent to your Telegram - Enter your 2FA password if you have one

Step 5: Add to Claude Desktop

Find your Claude Desktop config file: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/python",
      "args": ["/path/to/mcp-telegram/src/mcp_telegram/main.py"]
    }
  }
}

To find paths: - Python: Run which python (Mac) or where.exe python (Windows) - main.py: Right-click the file and select "Copy Path"

Restart Claude Desktop.

Usage

After setup, you can ask Claude to: - "Check my Telegram messages" - "Send a message to [contact name]" - "What are my unread chats?" - "Reply to the last message from [contact name]"

Style Guide (Optional)

Create src/mcp_telegram/convostyle.txt to help Claude match your texting style:

I text casually with friends, formally with work contacts.
I use emojis sparingly and prefer short messages.

Troubleshooting

Authentication Issues

If authentication fails: 1. Check your API credentials in .env 2. Remove the TELEGRAM_SESSION_STRING line from .env 3. Run python telethon_auth.py again

Common Errors

"Please set TELEGRAM_API_ID and TELEGRAM_API_HASH": Missing .env file or credentials
"Session string is invalid or expired": Re-run authentication
2FA password not showing: This is normal - keep typing