telethon-mcp

Telegram MCP Server — control Telegram through Claude using the Telethon library.

46 tools across messaging, chats, contacts, media, admin, and advanced features — powered by Telethon, the full-featured Telegram MTProto client.

Tools

Messaging (8)

Tool	Description
send_message	Send a message to a chat or user
edit_message	Edit a sent message
delete_message	Delete a message
forward_message	Forward a message to another chat
reply_to_message	Reply to a specific message
get_messages	Get messages from a chat
search_messages	Search messages across chats
pin_message	Pin or unpin a message

Chats (8)

Tool	Description
list_chats	List all chats and groups
get_chat_info	Get details about a chat
create_group	Create a new group
create_channel	Create a new channel
join_chat	Join a chat via link or username
leave_chat	Leave a chat
archive_chat	Archive or unarchive a chat
mute_chat	Mute or unmute a chat

Contacts (6)

Tool	Description
list_contacts	List all contacts
add_contact	Add a new contact
delete_contact	Remove a contact
block_user	Block a user
unblock_user	Unblock a user
get_user_info	Get detailed info about a user

Media (6)

Tool	Description
send_photo	Send a photo
send_document	Send a file/document
send_voice	Send a voice message
send_video	Send a video
download_media	Download media from a message
get_profile_photo	Get a user or chat's profile photo

Admin (9)

Tool	Description
ban_user	Ban a user from a group/channel
unban_user	Unban a user
kick_user	Kick a user from a group
promote_admin	Promote a user to admin
demote_admin	Remove admin rights from a user
set_chat_title	Change a chat's title
set_chat_photo	Change a chat's photo
get_participants	List all members of a group/channel
invite_user	Invite a user to a group/channel

Advanced (9)

Tool	Description
send_reaction	Add a reaction to a message
create_poll	Create a poll in a chat
schedule_message	Schedule a message for later
get_scheduled_messages	List scheduled messages
delete_scheduled_message	Delete a scheduled message
set_typing	Send typing indicator
mark_as_read	Mark messages as read
get_drafts	Get saved drafts
save_draft	Save a message draft

---

Setup

Prerequisites

• Python 3.10+
• uv package manager
• Telegram API credentials (free from Telegram)

Step 1 — Get Telegram API Credentials

1. Go to my.telegram.org/apps
2. Log in with your Telegram phone number
3. Click "Create new application"
4. Fill in the form (App title and short name can be anything)
5. Copy your API ID (number) and API Hash (string)

Step 2 — Install

pip install telethon-mcp
# or with uv:
uv add telethon-mcp

Step 3 — Generate Session String

python -m telethon_mcp.generate_session
# or after install:
generate-session

This opens an interactive flow:

1. Enter your API ID and API Hash
2. Enter your phone number (with country code)
3. Enter the OTP sent to your Telegram
4. Enter your 2FA password if enabled
5. Copy the generated session string

Step 4 — Configure

Create a .env file in your working directory:

TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
TELEGRAM_SESSION_STRING=your_session_string

Step 5 — Add to Claude Code

claude mcp add telegram -- uvx telethon-mcp

Or manually in your Claude config (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": ["telethon-mcp"],
      "env": {
        "TELEGRAM_API_ID": "your_api_id",
        "TELEGRAM_API_HASH": "your_api_hash",
        "TELEGRAM_SESSION_STRING": "your_session_string"
      }
    }
  }
}

---

Security

• Session string gives full access to your Telegram account — treat it like a password
• Never commit your .env file or session string to version control
• Add .env to your .gitignore
• To revoke access: go to Telegram Settings → Privacy → Active Sessions → terminate the session

---

Troubleshooting

"TELEGRAM_SESSION_STRING not set": Run generate-session and add the output to your .env.

"AuthKeyError" or session invalid: Your session expired or was revoked. Run generate-session again.

Flood wait errors: Telegram rate-limits heavy usage. The server will wait automatically.

2FA required during session generation: Enter your Two-Step Verification password when prompted.

---

Requirements

• Python 3.10+
• A Telegram account
• Telegram API credentials (free from my.telegram.org)

License

MIT — Hitesh Gupta