iflow-mcp_telegram-mcp 0.1.1
A Telegram MCP server for reading and writing messages.
Requires Python: >=3.10
Keywords: telegram, mcp, claude, ai, llm

# 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