overpod/mcp-telegram

> **📖 Documentation** · **☁️ Cloud version** — connect Telegram to Claude.ai or ChatGPT in 30 seconds with QR code, no API keys needed.
**Telegram MCP Server** — a Model Context Protocol server that connects AI assistants like Claude and ChatGPT to Telegram via the MTProto protocol. Unlike bots, this runs as a **userbot** -- it operates under your personal Telegram account using GramJS, giving full access to your chats, contacts, and message history.
Features
- **Comprehensive tool coverage** -- the most full-featured Telegram MCP server available
- **MTProto protocol** -- direct Telegram API access, not the limited Bot API
- **Userbot** -- operates as your personal account, not a bot
- **Full-featured** -- messaging, reactions, polls, scheduled messages, stickers, media, contacts, and more
- **Forum Topics** -- list topics, read per-topic messages, send to specific topics, per-topic unread counts
- **Stickers** -- search sticker sets, browse installed/recent stickers, send stickers to any chat
- **Account & profile management** -- update profile, set emoji status, birthday, personal channel, profile photo, manage privacy settings, sessions, auto-delete timers
- **Chat folders** -- create, edit, delete and reorder folders, toggle folder tags, read suggested folders (v1.33.0)
- **Global privacy** -- read and set account-wide privacy settings (v1.33.0)
- **Global search** -- search messages across all chats at once
- **Real-time polling** -- fetch updates via stateless cursors; agent owns {pts, qts, date} state
- **Inline bots & buttons** -- query inline bots, send results, press callback buttons
- **Stories** -- read stories from peers, get story view stats; publish/edit/delete stories, react, pin, stealth mode, archive, report (v1.30.0)
- **Discussion** -- get discussion-group info for channel posts with comments, list groups eligible for discussion (v1.30.0)
- **Read Receipts** -- who read a message in a small group, when your private message was read (v1.30.0)
- **Admin controls** -- toggle channel signatures, anti-spam, forum mode, prehistory; approve join requests
- **Stats** -- channel and supergroup analytics (GetBroadcastStats / GetMegagroupStats)
- **Boosts & Business** -- boost status, boosters list, Telegram Business chat links CRUD, work hours, location, greeting/away/intro messages
- **Star gifts** -- browse available and saved gifts, save/convert gifts, manage Stars balance and subscriptions (opt-in via MCP_TELEGRAM_ENABLE_STARS=1, v1.34.0)
- **Shared daemon** -- one background process serves multiple MCP clients over a single Telegram session; see the shared-daemon guide (v1.38.0)
- **QR code login** -- authenticate by scanning a QR code in the Telegram app
- **Session persistence** -- login once, stay connected across restarts
- **Human-readable output** -- sender names are resolved, not just numeric IDs
- **Works with any MCP client** -- Claude Code, Claude Desktop, ChatGPT, Cursor, VS Code, Mastra, etc.
Prerequisites
- **Node.js** 18 or later
- **Telegram API credentials** -- API_ID and API_HASH from my.telegram.org
Quick Start
1. Get Telegram API credentials
1. Go to my.telegram.org and log in with your phone number.
2. Navigate to **API development tools**.
3. Create a new application (any name and platform).
4. Copy the **App api_id** and **App api_hash**.
2. Login
A QR code will appear in the terminal. Open Telegram on your phone, go to **Settings > Devices > Link Desktop Device**, and scan the code. The session is saved to ~/.mcp-telegram/session and reused automatically.
> **Custom session path:** set TELEGRAM_SESSION_PATH=/path/to/session to store the session file elsewhere.
> **Two-step verification (2FA):** if your account has a cloud password enabled, scanning the QR code is not enough — Telegram also requires the password. Provide it via TELEGRAM_2FA_PASSWORD so the login can complete:
>
>
>
> The password is only used locally to answer Telegram's SRP challenge and is never persisted.
3. Add to Claude
That's it! Ask Claude to run telegram-status to verify.
Multiple Accounts
Use TELEGRAM_SESSION_PATH to run separate Telegram accounts side by side: