Skip to content

README.md

Latest commit

 

History

History
120 lines (88 loc) · 2.6 KB

README.md

File metadata and controls

120 lines (88 loc) · 2.6 KB

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.