mcp-telegram
If you are the rightful owner of mcp-telegram and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
Telegram MCP Server allows Claude to access your Telegram account for reading and sending messages.
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
- Reads your conversation style guide from
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) orwhere.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:
- Check your API credentials in
.env - Remove the TELEGRAM_SESSION_STRING line from
.env - Run
python telethon_auth.pyagain
Common Errors
- "Please set TELEGRAM_API_ID and TELEGRAM_API_HASH": Missing
.envfile 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
