A Model Context Protocol (MCP) server that connects , , , , VS Code, Cline, Windsurf, Goose, and any other MCP-compatible client to a real Telegram user account via —so your agent can read, search, send, moderate, and manage Telegram chats from chat or automated tool calls instead of clicking through the Telegram UI.
Telegram MCP server (MTProto). Connect Claude, Cursor, Claude Code, VS Code, Codex, Cline, Windsurf to a real Telegram account — read/search/send messages, moderate channels, manage stories/contacts/folders, transcribe voice, and call any raw MTProto method. Browser-based sign-in. 100+ tools.
Use it to: read dialogs and search messages globally · send/edit/forward/react/poll · download media and transcribe voice notes · moderate channels (ban/restrict/promote, invite links, slow-mode, admin log, forum topics) · manage stories, contacts, drafts, notifications, folders, privacy · or fall through to the raw MTProto bridge for anything else. All against a single signed-in user account—no bot required.
[!WARNING]
This server signs in as a real Telegram user (not a bot). Sessions live in ~/.telegram-agent/. Treat that directory like a password.
This package is the MCP server — every tool schema (~12,700 tokens) sits in your agent's context on every turn. Good for any MCP client and for hosted runtimes that can't shell out.
If your agent is Claude Code / Codex CLI / Cursor / Gemini CLI / Cline / Windsurf, there's a companion package — telegram-agent — that ships the same Telegram surface as a universal agent skill. The agent only loads the skill instructions when your prompt mentions Telegram — ~50× lower context cost in idle. Standalone (no MCP server in the loop), but uses the same ~/.telegram-agent/ session store as this package — sign in once, use either or both.
npm i -g telegram-agent
telegram-agent login
npx skills add beautyfree/telegram-agent -a claude-code -g
add-mcp (from Neon) writes the correct config for Claude Desktop, Claude Code, Cursor, VS Code, Codex, Gemini CLI, Cline, Zed, Goose, OpenCode, and others. Pick the client in the interactive prompt.
The agent calls the login tool. A browser tab opens. Enter your phone number, the SMS code, and 2FA password if you have one. The tab shows a green checkmark — you can close it. The session is now stored locally and the agent can read your Telegram.
To add another account, ask the agent to call login again.
Tools
102 tools covering the full Telegram user-account surface. Common ones below; the rest are grouped under collapsibles. Every tool accepts an optional accountId (omit when only one account is signed in). peer accepts a numeric chat id, an @username, or the literal "me" (Saved Messages).
Top of the menu:
Tool
What it does
login
Open the browser-based sign-in flow. Adds an account.
list_accounts
List signed-in accounts.
list_dialogs
List dialogs/chats/channels. Filters: unread, archived, ignorePinned, folder, limit.
list_messages
List messages in a dialog. Newest first.
search_messages
Search inside one dialog: query, filter (photos/videos/url/voice/...), fromUser, date range.
Send a file (local path or https:// URL). Pass an array for an album.
download_media
Save the media on a message to disk.
transcribe_message
Transcribe a voice/video note (Premium).
invoke_mtproto
Call any raw MTProto method by name. Auto-resolves peer/channel/user strings.
These are local-only: they manage which Telegram sessions live in ~/.telegram-agent/ and the settings UI. No Telegram API call beyond the sign-in flow itself.
Tool
What it does
list_accounts
List signed-in accounts.
login
Browser-based sign-in. Adds an account.
logout
Drop a local session and revoke it on Telegram.
open_settings
Open the local settings page (tool surface + read-only).
Tool
What it does
get_me
Return the profile of the authenticated user.
update_profile
Change own first/last name and bio.
update_my_username
Set or clear own @username.
set_birthday
Set the account birthday.
set_profile_photo
Upload a new avatar (local path or URL).
Tool
What it does
list_dialogs
List dialogs. Filters: unread, archived, ignorePinned, folder, limit.
search_dialogs
Find dialogs by name/title/username substring.
resolve_username
Resolve @username to a user/channel/chat entity.
list_folders
List custom dialog folders (chat filters).
list_contacts
List contacts.
Tool
What it does
list_messages
List messages in a dialog.
search_messages
Search inside one dialog (text, type filter, sender, date range).
search_global
Search across every chat.
get_message
Fetch one or more messages by id.
get_message_reactions
Get reactions on messages.
mark_as_read
Mark messages read up to an id.
Tool
What it does
send_message
Send text.
edit_message
Edit a previously sent message.
delete_messages
Delete by id (optionally revoke for all).
forward_messages
Forward messages between dialogs.
pin_message / unpin_message
Pin / unpin in a dialog.
send_reaction
Set reactions on a message.
send_message_to_phone
Send to a phone number, auto-creates a temporary contact.
Tool
What it does
send_file
Send a file (path or URL). Albums via array.
download_media
Save a message's media to disk.
download_profile_photo
Save a peer's avatar to disk.
transcribe_message
Transcribe voice/video (Premium).
Tool
What it does
send_poll
Send a poll. Supports quiz, multiple-choice, anonymous, close period.
vote_poll
Cast a vote.
close_poll
Finalize a poll.
get_poll_results
Fetch tally.
Tool
What it does
send_reaction
Set emoji reactions on a message.
get_message_reactions
Read reactions.
set_default_reaction
Set account-wide default.
Tool
What it does
list_stories
Feed of contacts' stories.
get_peer_stories
One peer's stories.
send_story
Post a story (photo or video).
delete_story
Delete own stories.
view_story
Mark stories viewed.
get_story_viewers
List who viewed your story.
Tool
What it does
ban_user
Full ban (optional untilDate).
unban_user
Lift restrictions.
restrict_user
Apply a custom rights mask.
promote_admin
Grant admin rights (with rank).
demote_admin
Strip admin rights.
invite_user
Add users to a channel/supergroup.
kick_participant
Kick from chat/channel.
get_participant
Single participant info.
list_participants
Members with filter (admins/banned/bots/...) and substring search.
delete_user_history
Remove every message by a user.
get_admin_log
Recent admin events with event-type filter.
Tool
What it does
edit_title
Change title (works for channels, supergroups, and basic groups).
edit_about
Change description.
edit_photo
Change avatar (path or URL).
update_username
Set/clear public @username.
check_username
Check availability.
set_slow_mode
Set slow-mode seconds.
toggle_signatures
Author signatures on channel posts.
toggle_pre_history_hidden
Hide history from new members.
toggle_join_request
Require admin approval to join.
leave_channel
Leave a channel/supergroup.
get_channel_info
Extended info (about, counts, linked chat, slow-mode).
get_user_info
Extended user info (bio, common chats).
Tool
What it does
create_channel
New broadcast channel or supergroup (optional forum mode).
delete_channel
Permanently delete.
migrate_chat
Basic group → supergroup.
transfer_ownership
Hand over creator rights (requires 2FA password).
Tool
What it does
create_invite_link
New link with optional expiry, usage cap, join-request gate.
list_invite_links
List active or revoked links.
revoke_invite_link
Revoke a specific link.
list_invite_joiners
List users that joined via a link.
Tool
What it does
list_topics
List forum topics.
create_topic
Create a new topic.
edit_topic
Rename, re-icon, close, hide.
Tool
What it does
save_draft
Save a draft for a dialog.
clear_draft
Drop the draft for a dialog.
list_drafts
List all dialog drafts.
Tool
What it does
mute_peer
Mute a chat (optional untilDate).
unmute_peer
Unmute.
get_notify_settings
Read settings.
set_notify_settings
Update mute, previews, sound, story-mute.
Tool
What it does
create_folder
New folder with include/exclude rules.
edit_folder
Replace folder rules.
delete_folder
Remove a folder.
reorder_folders
Set display order.
Tool
What it does
list_contacts
All contacts.
add_contact
Add a user to contacts.
delete_contact
Remove users from contacts.
search_contacts
Search contacts + global directory.
Tool
What it does
block_user / unblock_user
Block / unblock.
list_blocked
Block list.
get_privacy
Read a privacy key.
set_privacy
Update a privacy key (mode + allow/disallow lists).
Tool
What it does
get_my_stickers
Installed sticker sets.
install_sticker_set
Install by short name.
add_recent_sticker
Pin a sticker to recent.
Tool
What it does
get_my_boosts
List your boost slots.
apply_boost
Apply slots to a channel.
Tool
What it does
get_inline_bot_results
Run an inline bot query.
invoke_mtproto
Call any MTProto method by qualified name (e.g. messages.SendMessage, stories.GetAllStories). String values for peer/channel/user/fromPeer/toPeer/bot/chat are auto-resolved to InputPeer / InputUser.
From my.telegram.org/apps. If unset, the auth page prompts for it and saves to state.json.
TELEGRAM_API_HASH
yes
—
Same as above.
TELEGRAM_AGENT_HOME
no
~/.telegram-agent
State + per-account session storage. Legacy MCP_TELEGRAM_HOME still accepted. If only ~/.mcp-telegram exists from a previous install, it's used automatically.
TELEGRAM_AGENT_DOWNLOADS
no
$TELEGRAM_AGENT_HOME/downloads
Where download_media / download_profile_photo save files. Legacy MCP_TELEGRAM_DOWNLOADS still accepted.
MCP_TELEGRAM_READONLY
no
—
Set to 1/true/yes to hide every destructive tool.
MCP_TELEGRAM_TOOLS
no
—
Strict allowlist. Comma-separated tool names; supports prefix* wildcards. If set, anything not matched is hidden.
MCP_TELEGRAM_DISABLE
no
—
Blocklist applied after the allowlist. Same syntax.
LOG_LEVEL
no
info
debug for verbose stderr.
Choosing which tools the agent sees
The three gating vars stack — MCP_TELEGRAM_READONLY → MCP_TELEGRAM_TOOLS → MCP_TELEGRAM_DISABLE.
# Read-only agent — every mutating tool is hidden
MCP_TELEGRAM_READONLY=1
# Discovery-only — only login + the list/search/get tools
MCP_TELEGRAM_TOOLS='login,list*,search*,get*,resolveUsername'
# Allow writes but keep destructive ones away from the agent
MCP_TELEGRAM_DISABLE='delete*,ban*,kick*,create_channel,delete_channel,transfer_ownership,invokeMtproto'
# Specific surface: read + send/edit only
MCP_TELEGRAM_TOOLS='login,list_accounts,list_dialogs,list_messages,search_messages,search_global,send_message,editMessage'
In an MCP client config, drop these into the same env block as TELEGRAM_API_ID/TELEGRAM_API_HASH. To verify, re-open your client — the tools the server advertises are exactly the ones registered after the gates run.
Data layout
~/.telegram-agent/
├── state.json known accounts (no secrets in here)
└── sessions/
└── <account_id>/ per-account MTProto session
If a Telegram session is invalidated server-side (logged out from another device, password rotated, etc.), the next tool call returns an error telling the agent to call login to re-authorize.
Development
git clone https://github.com/beautyfree/mcp-telegram
cd mcp-telegram
npm install
echo "TELEGRAM_API_ID=...\nTELEGRAM_API_HASH=..." > .env
npm run dev
Layout:
src/
├── index.ts bin entry — stdio MCP server, tool registrations
├── telegram.ts MTProto client + login state machine
├── auth-browser.ts ephemeral HTTP server that drives the browser flow
├── auth-page.ts inline HTML for the auth page
├── state.ts persistent state in ~/.telegram-agent/
└── logger.ts
Telegram MCP · MCP Telegram · Telegram MCP server · Telegram for Claude · Telegram for Cursor · Telegram for Claude Code · Telegram for VS Code · Telegram for Codex · Telegram for Cline · Telegram for Windsurf · Telegram for AI agents · Telegram MTProto MCP · Telegram user-account MCP · Telegram automation MCP · Model Context Protocol Telegram · MCP server Telegram · gramjs MCP
M
MCP Telegram
beautyfree·33 ดาว·
Telegram MCP server (MTProto). Connect Claude, Cursor, Claude Code, VS Code, Codex, Cline, Windsurf to a real Telegram account — read/search/send messages, moderate channels, manage stories/contacts/f
Telegram MCP server (MTProto). Connect Claude, Cursor, Claude Code, VS Code, Codex, Cline, Windsurf to a real Telegram account — read/search/send messages, moderate channels, manage stories/contacts/folders, transcribe voice, and call any raw MTProto method. Browser-based sign-in. 100+ tools.
ตรวจสอบล่าสุดเมื่อ 2026-10-28 Telegram MCP server (MTProto). Connect Claude, Cursor, Claude Code, VS Code, Codex, Cline, Windsurf to a real Telegram account — read/search/send messages, moderate channels, manage stories/contacts/folders, transcribe voice, and call any raw MTProto method. Browser-based sign-in. 100+ tools.