README.md•3.29 kB
# 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
## Setup Guide
### Step 1: Get Telegram API Credentials
1. Go to [https://my.telegram.org/apps](https://my.telegram.org/apps)
2. Log in and create an application
3. Save your **API ID** and **API Hash**
### Step 2: Install
```bash
# 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
```bash
# 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
```bash
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:
```json
{
"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
## Requirements
- Python 3.10+
- Claude Desktop
- Telegram account
## License
Apache 2.0