MCP Telegram
About
Telegram MCP server with 20 tools — read chats, search messages, download media via MTProto
Details
- Author
- overpod
- Categories
- Communication, Search, Knowledge Base, Other, Productivity
Jump to
Setup
Install MCP Telegram in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/overpod/mcp-telegram
Follow the installation instructions in the repository README, then restart your MCP client.
📖 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 auserbot-- it operates under your personal Telegram account usingGramJS, giving full access to your chats, contacts, and message history.
- 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 viaMCP_TELEGRAM_ENABLE_STARS=1, v1.34.0)
- Shared daemon-- one background process serves multiple MCP clients over a single Telegram session; see theshared-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.
- Node.js18 or later
- Telegram API credentials--API_IDandAPI_HASHfrommy.telegram.org
- Go tomy.telegram.organd log in with your phone number.
- Navigate toAPI development tools.
- Create a new application (any name and platform).
- Copy theApp api_idandApp api_hash.
TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH npx @overpod/mcp-telegram login
A QR code will appear in the terminal. Open Telegram on your phone, go toSettings > Devices > Link Desktop Device, and scan the code. The session is saved to~/.mcp-telegram/sessionand reused automatically.
Custom session path:setTELEGRAM_SESSION_PATH=/path/to/sessionto 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 viaTELEGRAM_2FA_PASSWORDso the login can complete:
TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH TELEGRAM_2FA_PASSWORD=YOUR_PASSWORD npx @overpod/mcp-telegram login
The password is only used locally to answer Telegram's SRP challenge and is never persisted.
claude mcp add telegram -s user \ -e TELEGRAM_API_ID=YOUR_ID \ -e TELEGRAM_API_HASH=YOUR_HASH \ -- npx @overpod/mcp-telegram
That's it! Ask Claude to runtelegram-statusto verify.
UseTELEGRAM_SESSION_PATHto run separate Telegram accounts side by side:
# Login each account with a unique session path TELEGRAM_API_ID=ID1 TELEGRAM_API_HASH=HASH1 TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-work npx @overpod/mcp-telegram login TELEGRAM_API_ID=ID2 TELEGRAM_API_HASH=HASH2 TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-personal npx @overpod/mcp-telegram login
claude mcp add telegram-work -s user \ -e TELEGRAM_API_ID=ID1 \ -e TELEGRAM_API_HASH=HASH1 \ -e TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-work \ -- npx @overpod/mcp-telegram claude mcp add telegram-personal -s user \ -e TELEGRAM_API_ID=ID2 \ -e TELEGRAM_API_HASH=HASH2 \ -e TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-personal \ -- npx @overpod/mcp-telegram
Each account gets its own session file — no conflicts.
Multiple agents / concurrent clients (shared daemon)
The opposite of multiple accounts:oneaccount driven bymanyclients at once — several Claude Code windows, parallel sub-agents, or multiple IDEs. Normally each process opens the same session and they evict one another withAUTH_KEY_DUPLICATED. Serve mode fixes this.
Run a single persistentdaemonthat owns the one Telegram connection. Every other process auto-detects the daemon (via a PID lock) and becomes a thin client that proxies tool calls to it over a local Unix socket:
# On the host, once: start the daemon (owns the connection, no stdio) TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH mcp-telegram serve # (or set MCP_TELEGRAM_DAEMON=1 instead of the serve argument)
Then point each MCP client at the same install with the sameTELEGRAM_SESSION_PATH— noserveargument. They connect to the daemon automatically; closing any client never drops the shared connection. Credentials are only required by the daemon (the owner), so client commands can omitTELEGRAM_API_ID/TELEGRAM_API_HASHand keep them where the daemon runs.
See theshared daemon guidefor a systemd unit and SSH usage.
If Telegram is blocked or you're running in a containerized environment (Docker, K3s), use a SOCKS5 or MTProxy:
# SOCKS5 proxy TELEGRAM_PROXY_IP=127.0.0.1 \ TELEGRAM_PROXY_PORT=10808 \ npx @overpod/mcp-telegram # MTProxy TELEGRAM_PROXY_IP=proxy.example.com \ TELEGRAM_PROXY_PORT=443 \ TELEGRAM_PROXY_SECRET=ee00000000000000000000000000000000 \ npx @overpod/mcp-telegram
If your VPS or hosting IP is reachable on outbound port443but not the default MTProto port80(some cloud providers ban port80on Telegram DC IP ranges as anti-abuse policy), set:
TELEGRAM_USE_WSS=true npx @overpod/mcp-telegram
No need to clone or install anything. Just usenpx @overpod/mcp-telegram.
npm install -g @overpod/mcp-telegram mcp-telegram # run server mcp-telegram login # QR login
Download fromReleases— standalone single-file binaries, zero dependencies:
# Download (example for Linux x64) curl -L -o mcp-telegram https://github.com/mcp-telegram/mcp-telegram/releases/latest/download/mcp-telegram-linux-x64 curl -L -o mcp-telegram-login https://github.com/mcp-telegram/mcp-telegram/releases/latest/download/mcp-telegram-login-linux-x64 chmod +x mcp-telegram mcp-telegram-login # Login TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH ./mcp-telegram-login # Run ./mcp-telegram
git clone https://github.com/mcp-telegram/mcp-telegram.git cd mcp-telegram npm install && npm run build
docker build -t mcp-telegram https://github.com/mcp-telegram/mcp-telegram.git
docker run -it --rm \ -e TELEGRAM_API_ID=YOUR_ID \ -e TELEGRAM_API_HASH=YOUR_HASH \ -v ~/.mcp-telegram:/root/.mcp-telegram \ --entrypoint node mcp-telegram dist/qr-login-cli.js
docker run -i --rm \ -e TELEGRAM_API_ID=YOUR_ID \ -e TELEGRAM_API_HASH=YOUR_HASH \ -v ~/.mcp-telegram:/root/.mcp-telegram \ mcp-telegram
Note: Login must be done once via terminal. After that, the session is persisted in~/.mcp-telegramand reused automatically.
claude mcp add telegram -s user \ -e TELEGRAM_API_ID=YOUR_ID \ -e TELEGRAM_API_HASH=YOUR_HASH \ -- npx @overpod/mcp-telegram
- macOS:~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:%APPDATA%\Claude\claude_desktop_config.json
{ "mcpServers": { "telegram": { "command": "npx", "args": ["@overpod/mcp-telegram"], "env": { "TELEGRAM_API_ID": "YOUR_ID", "TELEGRAM_API_HASH": "YOUR_HASH" } } } }
Ask Claude:"Run telegram-login"-- a QR code will appear. If the image is not visible, it's also saved to~/.mcp-telegram/qr-login.png. Scan it in Telegram (Settings > Devices > Link Desktop Device).
Ask Claude:"Run telegram-status"to verify the connection.
Note: No terminal required! Login works entirely through Claude Desktop.
Same setup, but using the pre-built binary instead of npx:
{ "mcpServers": { "telegram": { "command": "/path/to/mcp-telegram", "env": { "TELEGRAM_API_ID": "YOUR_ID", "TELEGRAM_API_HASH": "YOUR_HASH" } } } }
-
Login via terminal first (seeDockersection above).
{ "mcpServers": { "telegram": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "TELEGRAM_API_ID=YOUR_ID", "-e", "TELEGRAM_API_HASH=YOUR_HASH", "-v", "~/.mcp-telegram:/root/.mcp-telegram", "mcp-telegram" ] } } }
- Restart Claude Desktop. Ask Claude:"Run telegram-status"to verify.
Add the same JSON config above to your MCP settings (Cursor Settings > MCP, or VS Code MCP config).
import { MCPClient } from "@mastra/mcp"; const telegramMcp = new MCPClient({ id: "telegram-mcp", servers: { telegram: { command: "npx", args: ["@overpod/mcp-telegram"], env: { TELEGRAM_API_ID: process.env.TELEGRAM_API_ID!, TELEGRAM_API_HASH: process.env.TELEGRAM_API_HASH!, }, }, }, });
All tools are auto-discoverable via MCP — your AI client will see the full list with parameters and descriptions when connected.
Tip: Ask your AI assistant"What Telegram tools are available?"to get the full list with parameters and descriptions.
Some tools are disabled by default and must be opted in via environment variables:
Add these to your.envfile or MCP client config to enable them.
npm run dev # Start with file watching (tsx) npm start # Start the MCP server npm run login # QR code login in terminal npm run build # Compile TypeScript npm run lint # Check code with Biome npm run lint:fix # Auto-fix lint issues npm run format # Format code with Biome
src/ index.ts -- MCP server entry point telegram-client.ts -- TelegramService class (GramJS wrapper) qr-login-cli.ts -- CLI utility for QR code login tools/ -- Modular tool definitions auth.ts -- Connection & login messages.ts -- Send, read, search, edit, delete, forward; inline bots; real-time polling chats.ts -- Chat listing, group management, admin toggles, stats contacts.ts -- Contacts, profiles, moderation media.ts -- Files, photos, downloads reactions.ts -- Reactions, set-chat-reactions extras.ts -- Pin, schedule, polls, topics stickers.ts -- Sticker sets, send, search, browse account.ts -- Sessions, privacy, auto-delete, profile, emoji status, birthday, chat mute/folders, invite links business.ts -- Telegram Business: chat links CRUD, work hours, location, greeting/away/intro boosts.ts -- Boost status, my boosts, boosters list stories.ts -- Stories: list all, peer, by-id, view stats group-calls.ts -- Group call info and participants (opt-in: MCP_TELEGRAM_ENABLE_GROUP_CALLS) stars.ts -- Stars wallet status and transactions (opt-in: MCP_TELEGRAM_ENABLE_STARS) quick-replies.ts -- Quick replies and messages (opt-in: MCP_TELEGRAM_ENABLE_QUICK_REPLIES) shared.ts -- Shared utilities
- TypeScript-- ES2022, ESM modules
- GramJS(telegram) -- Telegram MTProto client
- @modelcontextprotocol/sdk-- MCP server framework
- Zod-- Runtime schema validation for tool parameters
- Biome-- Linter and formatter
- tsx-- TypeScript execution without a build step
- dotenv-- Environment variable management
A Telegram session can only be used byone process at a time. If you getAUTH_KEY_DUPLICATED, it means another process is already using the same session file.
Solution: Create separate sessions for each environment:
# Local development TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-local npx @overpod/mcp-telegram login # Production server TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-prod npx @overpod/mcp-telegram login
Then setTELEGRAM_SESSION_PATHin each environment's MCP config accordingly.
- API credentials are stored in.env(gitignored)
- Session is stored in~/.mcp-telegram/sessionwith0600permissions (owner-only access)
- Session directory is created with0700permissions
- Phone number isnot required-- QR-only authentication
- No data is sent to third-party services -- all communication goes directly to Telegram servers via MTProto
- QR login codes are generated locally and never leave your machine
- One session per process-- using the same session in multiple processes simultaneously causesAUTH_KEY_DUPLICATEDerrors (seeTroubleshooting)
- This is auserbot(personal account), not a bot -- respect theTelegram Terms of Service
Connect Claude, ChatGPT, and other AI tools to your Granola meeting notes via MCP. Query your notes, search transcripts, and get meeting insights in your favorite AI assistants.
MCP server for full Gmail operations via Unipile API. 9 tools: send, reply, list, read, delete, search, labels, attachments, drafts. Dry-run by default, 55 unit tests. MIT licensed.
MCP server for Stalwart mail server via JMAP — mailboxes, search, send, and admin
Search, read, and send personal WhatsApp messages, contacts, and media files.
A WhatsApp MCP (Model Context Protocol) server that connects your WhatsApp account with AI agents, enabling automated messaging, contact search, and chat interaction through LLMs.
Connect your Plaud recordings to any MCP-compatible AI client. Search recordings, read transcripts, and generate documents without leaving your AI assistant.
Agent-native forum for the x402/A2A ecosystem. The hosted MCP server exposes the whole forum as tools — threads, comments, votes, USDC bounties (Coinbase x402 on Base), provider reviews, and search. Endpoint: https://api.achivx.com/mcp/ (HTTP, OAuth 2.1).
MCP server for Telegram bots built with aiogram. 30 tools, 7 resources, 3 prompts — messaging, rich media, moderation, interactive keyboards, real-time event streaming, rate limiting, permissions, and audit logging.
Production-grade MCP server for Telegram with dual-mode Bot API + MTProto, 6 composite tools
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
