telegram-statusLABSCO SUMMARY
This is your account, not a bot — the reach is the point and the risk.
Signing in as a user is what makes global search across every chat, story publishing and admin actions possible; a bot token cannot do any of it. That also means the session file is as good as your Telegram login, and the tool list includes banning members and terminating sessions. The env-gated groups are a sensible response: Stars and group calls stay absent until you deliberately enable them.
What it is
An MCP server that signs into Telegram as you (QR login, not a bot token) and exposes 181 auto-discoverable tools across the client API — reading and sending messages, moderating groups, stories, polls, stickers, folders, privacy and Telegram Business.
What you get
- Messaging —
telegram-send-message,telegram-edit-message,telegram-delete-message,telegram-forward-message,telegram-send-scheduled,telegram-translate-message,telegram-get-message-link - Reading —
telegram-list-chats,telegram-read-messages,telegram-search-messagesin one chat,telegram-search-globalacross all of them,telegram-get-unread,telegram-get-unread-mentions,telegram-get-replies - Groups and moderation —
telegram-create-group,telegram-invite-to-group,telegram-kick-user,telegram-ban-user,telegram-set-admin,telegram-set-chat-permissions,telegram-set-slow-mode,telegram-get-admin-log - Media —
telegram-send-file,telegram-download-media,telegram-send-voice,telegram-send-video-note,telegram-send-album,telegram-send-location,telegram-send-contact; allfilePatharguments must be absolute local paths, with URLs, path traversal and/proc-style pseudo-filesystems rejected - Stories, polls and reactions —
telegram-send-story,telegram-get-story-views,telegram-create-poll,telegram-vote-poll,telegram-get-poll-results,telegram-send-reaction,telegram-send-paid-reaction - Account and organisation —
telegram-get-sessions,telegram-terminate-session,telegram-set-privacy,telegram-create-folder,telegram-mute-chat,telegram-archive-chat,telegram-pin-message - Some tools stay unregistered unless you opt in: group calls behind
MCP_TELEGRAM_ENABLE_GROUP_CALLS=1, Stars behindMCP_TELEGRAM_ENABLE_STARS=1, quick replies behindMCP_TELEGRAM_ENABLE_QUICK_REPLIES=1 - Several features need Telegram Premium — audio transcription, stealth mode, emoji status — and the Business suite needs a Business subscription
Requirements
A Telegram API ID and API hash from my.telegram.org, set as TELEGRAM_API_ID and TELEGRAM_API_HASH, then a QR login that creates a local session file. The simplest install is a standalone binary from GitHub Releases — one file, no Node.js — with builds for macOS arm64 and x64, Linux x64 and arm64, and Windows x64. With Node.js 18+ you can instead run npx @overpod/mcp-telegram login then npx @overpod/mcp-telegram, or install globally, or use Docker. Package version 1.41.5.
Setup effort
One command plus credentials — npx @overpod/mcp-telegram, then supply credentials
USE CASES
01
Finding something you know you were told somewhere
Search across every chat at once, then read the surrounding messages of the hit that matches.
02
Clearing a backlog of unread chats
List chats with unread counts and mentions, read the ones that matter, and mark the rest as read.
03
Moderating a group without opening the app
Check your role, adjust default permissions or slow mode, and review the admin log for what changed.
04
Scheduling an announcement
Draft the message, schedule it for later, and confirm it appears in the chat's scheduled list.
181 tools
Listed in project docs. Your client may show a different list.
telegram-logintelegram-logouttelegram-send-messagetelegram-edit-messagetelegram-delete-messagetelegram-forward-messagetelegram-send-scheduledtelegram-send-typingtelegram-translate-messagetelegram-get-message-linktelegram-get-scheduledtelegram-delete-scheduledtelegram-list-chatstelegram-read-messagestelegram-search-messagestelegram-search-globaltelegram-search-chatstelegram-get-unreadtelegram-mark-as-readtelegram-get-repliestelegram-get-unread-mentionstelegram-get-unread-reactionstelegram-get-saved-dialogstelegram-save-drafttelegram-get-draftstelegram-clear-draftstelegram-list-topicstelegram-read-topic-messagestelegram-create-topictelegram-edit-topictelegram-delete-topictelegram-create-polltelegram-vote-polltelegram-get-poll-resultstelegram-get-poll-voterstelegram-close-polltelegram-send-reactiontelegram-get-reactionstelegram-set-default-reactiontelegram-get-top-reactionstelegram-get-recent-reactionstelegram-send-paid-reactiontelegram-toggle-paid-reaction-privacytelegram-get-paid-reaction-privacytelegram-transcribe-audiotelegram-get-transcriptiontelegram-rate-transcriptiontelegram-get-fact-checktelegram-edit-fact-checktelegram-delete-fact-checktelegram-send-stickertelegram-get-installed-stickerstelegram-get-recent-stickerstelegram-get-sticker-settelegram-search-sticker-setstelegram-send-filetelegram-download-mediatelegram-get-profile-phototelegram-get-web-previewtelegram-send-voicetelegram-send-video-notetelegram-send-locationtelegram-send-venuetelegram-send-contacttelegram-send-dicetelegram-send-albumtelegram-create-grouptelegram-edit-grouptelegram-invite-to-grouptelegram-join-chattelegram-leave-grouptelegram-kick-usertelegram-ban-usertelegram-unban-usertelegram-set-admintelegram-remove-admintelegram-get-my-roletelegram-set-chat-permissionstelegram-set-slow-modetelegram-get-admin-logtelegram-get-chat-infotelegram-get-chat-memberstelegram-get-chat-folderstelegram-create-foldertelegram-edit-foldertelegram-delete-foldertelegram-reorder-folderstelegram-get-suggested-folderstelegram-toggle-folder-tagstelegram-get-global-privacy-settingstelegram-set-global-privacy-settingstelegram-create-invite-linktelegram-get-invite-linkstelegram-revoke-invite-linktelegram-get-contactstelegram-add-contacttelegram-get-contact-requeststelegram-block-usertelegram-unblock-usertelegram-report-spamtelegram-get-profiletelegram-update-profiletelegram-set-emoji-statustelegram-list-emoji-statusestelegram-clear-recent-emoji-statusestelegram-set-profile-colortelegram-set-birthdaytelegram-set-personal-channeltelegram-set-profile-phototelegram-delete-profile-phototelegram-get-sessionstelegram-terminate-sessiontelegram-set-privacytelegram-set-auto-deletetelegram-pin-messagetelegram-unpin-messagetelegram-mute-chattelegram-archive-chattelegram-pin-chattelegram-mark-dialog-unreadtelegram-toggle-channel-signaturestelegram-toggle-anti-spamtelegram-toggle-forum-modetelegram-toggle-prehistory-hiddentelegram-set-chat-reactionstelegram-approve-join-requesttelegram-get-broadcast-statstelegram-get-megagroup-statstelegram-inline-querytelegram-inline-query-sendtelegram-press-buttontelegram-get-message-buttonstelegram-get-statetelegram-get-updatestelegram-get-channel-updatestelegram-get-all-storiestelegram-get-peer-storiestelegram-get-stories-by-idtelegram-get-story-viewstelegram-send-storytelegram-edit-storytelegram-delete-storiestelegram-react-to-storytelegram-export-story-linktelegram-read-storiestelegram-toggle-story-pinnedtelegram-toggle-story-pinned-to-toptelegram-activate-stealth-modetelegram-get-stories-archivetelegram-report-storytelegram-get-discussion-messagetelegram-get-groups-for-discussiontelegram-get-message-read-participantstelegram-get-outbox-read-datetelegram-get-my-booststelegram-get-boosts-statustelegram-get-boosts-listtelegram-get-business-chat-linkstelegram-create-business-chat-linktelegram-edit-business-chat-linktelegram-delete-business-chat-linktelegram-resolve-business-chat-linktelegram-set-business-hourstelegram-set-business-locationtelegram-set-business-greetingtelegram-set-business-awaytelegram-set-business-introtelegram-get-group-calltelegram-get-group-call-participantstelegram-get-stars-statustelegram-get-stars-transactionstelegram-get-stars-topup-optionstelegram-get-stars-subscriptionstelegram-change-stars-subscriptiontelegram-get-available-star-giftstelegram-get-saved-star-giftstelegram-save-star-gifttelegram-convert-star-gifttelegram-get-quick-repliestelegram-get-quick-reply-messagesBEFORE YOU INSTALL
What to know first
Tools you get
181 tools named in the project's documentation.
Requires
- npx on PATH
- Node.js 18 or later
- TELEGRAM_API_ID in your environment
- TELEGRAM_API_HASH in your environment
INSTALLATION
Connect your client
Server setup
TERMINAL
npx @overpod/mcp-telegramMCP Clients
Claude Code
CLAUDE CODE · TERMINAL
claude mcp add telegram -s user \
-e TELEGRAM_API_ID=<YOUR_TELEGRAM_API_ID> \
-e TELEGRAM_API_HASH=<YOUR_TELEGRAM_API_HASH> \
-- npx @overpod/mcp-telegramClaude Desktop — npx, Cursor — npx
JSON
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": [
"@overpod/mcp-telegram"
],
"env": {
"TELEGRAM_API_ID": "<YOUR_TELEGRAM_API_ID>",
"TELEGRAM_API_HASH": "<YOUR_TELEGRAM_API_HASH>"
}
}
}
}VS Code — npx
VS CODE — NPX · JSON
{
"servers": {
"telegram": {
"command": "npx",
"args": [
"@overpod/mcp-telegram"
],
"env": {
"TELEGRAM_API_ID": "<YOUR_TELEGRAM_API_ID>",
"TELEGRAM_API_HASH": "<YOUR_TELEGRAM_API_HASH>"
}
}
}
}Claude Desktop — binary
CLAUDE DESKTOP — BINARY · JSON
{
"mcpServers": {
"telegram": {
"command": "<YOUR_PATH_TO_MCP_TELEGRAM>",
"env": {
"TELEGRAM_API_ID": "<YOUR_TELEGRAM_API_ID>",
"TELEGRAM_API_HASH": "<YOUR_TELEGRAM_API_HASH>"
}
}
}
}
