Telegram User MCP

Send Telegram messages from your personal account (not a bot) via Claude Code.

Features

• send_message - Send messages as yourself
• send_file - Send files as yourself
• download_media - Download photos/files from chats to local folder
• delete_messages - Delete messages by ID
• get_dialogs - List your chats
• get_messages - Read messages from a chat
• add_contact - Add named contacts (e.g., "wife" → chat_id)

Setup

1. Get API credentials

1. Go to https://my.telegram.org
2. Log in with your phone number
3. Click "API development tools"
4. Create an application
5. Copy api_id and api_hash

2. Install

cd ~/telegram-user-mcp
uv venv --python 3.11
source .venv/bin/activate
uv pip install telethon python-dotenv "mcp>=1.0.0"

3. Configure

cp .env.example .env
# Edit .env with your credentials:
# TELEGRAM_API_ID=your_api_id
# TELEGRAM_API_HASH=your_api_hash
# TELEGRAM_PHONE=+1234567890
# CONTACT_WIFE=chat_id

4. Authorize (one time)

source .venv/bin/activate
python auth_with_code.py          # Request code
python auth_with_code.py CODE     # Sign in
python auth_with_code.py CODE PASSWORD  # If 2FA enabled

This will:

• Send a code to your Telegram
• Create a session file (saved locally)

5. Add to Claude Code

claude mcp add telegram-user -s user \
  -e TELEGRAM_API_ID=your_api_id \
  -e TELEGRAM_API_HASH=your_api_hash \
  -e TELEGRAM_PHONE=+your_phone \
  -e CONTACT_WIFE=chat_id \
  -- ~/telegram-user-mcp/.venv/bin/python ~/telegram-user-mcp/src/server.py

Usage

After setup, Claude can:

"Send my wife a message saying I'll be home late"
"Send this PDF to @username"
"Show me my recent chats"
"Download photos from Vera to my Desktop"

Download Media

Download photos and files from any chat to a local folder:

"Download photos from wife to ~/Desktop/photos"
"Save all files from @username to ~/Downloads"

Parameters:

• from_chat - Contact name, username, or chat_id
• save_to - Absolute path to folder (created if not exists)
• limit - How many recent messages to check (default: 20)
• media_type - "photo", "document", or "all" (default: all)

Delete Messages

Delete messages by their IDs:

"Delete messages 12345, 12346 from saved"

Note: In private chats you can only delete your own messages.

Security

• Session file is stored locally
• Never share your session file
• API credentials stay on your machine

Contacts

Add contacts in .env:

CONTACT_WIFE=155919668
CONTACT_BOSS=123456789

Or dynamically via the add_contact tool.