mcp-telegram

# 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