Telegram MCP Server

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

Features

Available Tools

1. 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

2. get_messages - Read messages from a specific chat

   • Fetches paginated message history

   • Automatically marks messages as read

3. mark_messages_read - Mark all unread messages in a chat as read

4. send_message - Send messages to any chat

   • Supports replying to specific messages

5. get_conversation_context - Analyze chat style for natural responses

   • Reads your conversation style guide from convostyle.txt

   • Helps Claude match your texting patterns

Related MCP server: Twitter MCP Server

Setup Guide

Step 1: Get Telegram API Credentials

1. Go to https://my.telegram.org/apps

2. Log in and create an application

3. Save your API ID and API Hash

Step 2: Install

Step 3: Configure

Step 4: Authenticate

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:

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:

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

Requirements

• Python 3.10+

• Claude Desktop

• Telegram account

License

Apache 2.0