telegram-mcp-cli MCP server
Commit Nov 6, 2026Allows AI agents to interact with your real Telegram account via MTProto to read chats, search history, send messages, and manage media.
Also known as thenavidm/telegram-mcp-cli
- Stars
- 1
- Tools
- 31
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 6, 2026
- License
- MIT
What is telegram-mcp-cli MCP?
telegram-mcp-cli allows AI agents to interact with your real Telegram account via MTProto to read chats, search history, send messages, and manage media. It exposes 31 tools, such as whoami, resolve, list_chats.
Summary generated from the project's README
About telegram-mcp-cli MCP server
Managing your personal Telegram conversations through AI agents is what this tool enables. Unlike standard bot integrations that can only see messages sent directly to them, this server uses MTProto to sign in as your actual user account. This allows an agent to read your private group chats, search your entire message history, and respond on your behalf as if you were typing.
Developers can use this as a command line interface for scripting and automation or as an MCP server for clients like Claude Code, Cursor, and Claude Desktop. Setting it up requires a Telegram API ID, an API hash, and a session string obtained through a login process. The system provides 74 different tools covering everything from basic message sending and history reading to advanced management of media, polls, reactions, and group administration. It is designed to work locally via stdio, making it accessible for both terminal-based workflows and integrated AI coding environments.
What you can do with it
- 1Summarize missed group activityAsk your AI agent to catch you up on what happened in your group chats while you were away.
- 2Locate specific historical informationSearch through years of chat history to find specific details like passwords or old documents.
- 3Automate message repliesInstruct an agent to find a specific message and send a tailored response to the sender.
- 4Manage media and filesHave an AI agent download specific files or PDFs sent in your chats to your local machine.
Written from the project's README. Every use case is checked against a quote from it.
telegram-mcp-cli MCP tools 31
Detected from the READMEwhoamiresolvelist_chatsget_chathistorysearchdownload_medialist_contactssearch_contactsget_userlist_blockedget_participants
Show all 31 toolsShow fewer tools
get_full_chatget_pinnedget_reactionsget_scheduledmessage_linkcommon_chatssearch_publiclist_draftslist_foldersget_folderlist_sticker_setssearch_gifsmedia_infotranscribe_voicelist_topicslist_buttonslist_profile_photosget_privacyexport_contacts
Configuration
TELEGRAM_API_HASHTELEGRAM_API_IDTELEGRAM_AUDIT_LOGTELEGRAM_READ_ONLYTELEGRAM_SESSION
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablethenavidm/telegram-mcp-cli is public and reachablegithub.com/thenavidm/telegram-mcp-cli ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-06github.com/thenavidm/telegram-mcp-cli ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model31 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubTelegram MCP Server & CLI
Telegram MCP server and CLI for Claude Code, Codex and AI agents. 74 tools for chats, history, search, sending, media, contacts, groups, admin, topics, reactions, polls, folders and privacy, on your real account.
One install gives you both surfaces, the same tools under the same names, covering what the app does rather than what a bot is allowed to see.
Most Telegram integrations are bots, and a bot only ever receives messages sent to that bot. Your own conversations are invisible to it. This signs in as you over MTProto, so an agent can read the group you were actually talking in and answer in it.
Built and maintained by Navid Moazzez.
Two ways to use it
Command line
telegram-cli in your terminal, for scripting, cron, pipes, or just asking a
quick question without opening anything:
telegram-cli # every command, one line each
telegram-cli list-chats --unread-only --limit 10 # what needs an answer
telegram-cli history --peer @sarah --limit 20 # one conversation
telegram-cli search --query invoice # across every chat
telegram-cli send --peer me --text "note to self" # Saved Messages
telegram-cli list-chats --json | jq -r '.items[].name'
telegram-cli which search my messages # find the command for a task
telegram-cli <command> --help # what any command takes
--confirm is the shell spelling of the confirmation that deleting requires.
--json gives JSON, --compact puts it on one line, --agent turns on both
with no prompts and no color, and errors are JSON on stderr whichever you pick.
Built on Slipway, which turns one
definition of each tool into the MCP server and the CLI.
Reads return real objects rather than rendered text, so --json hands you
fields you can filter, and --fields id,text cuts the response before it is
ever printed.
MCP server, for AI agents
telegram-mcp is what Claude Code, Claude Desktop, Cursor and the rest launch.
You never run it by hand:
claude mcp add telegram \
-e TELEGRAM_API_ID=1234567 \
-e TELEGRAM_API_HASH=your_hash \
-e TELEGRAM_SESSION=your_session_string \
-- npx -y @thenavidm/telegram-mcp-cli
Then just ask: "what did I miss in the group chats while I was asleep?"
Every other client is in section 4.
Which one
| Where you are | What you can reach |
|---|---|
| An agent that can run shell commands, like Claude Code or Cursor | Both. The CLI is the cheaper one: nothing until it runs |
| claude.ai, the Claude Desktop chat tab, or a phone | The server only. There is no shell to run a command in |
| A terminal, a script, cron or CI | The CLI only. There is no MCP client in a shell |
They are the same program reading the same tool definitions, so anything one can do, the other can.
Features
74 tools. Every one is both a shell command and an MCP tool, under the same name; the command is the tool name with dashes.
These 13 are what the server loads by default, because they cover daily use:
| Capability | CLI command | MCP tool |
|---|---|---|
| Who am I | telegram-cli whoami |
whoami |
| Resolve a handle or id | telegram-cli resolve |
resolve |
| List chats | telegram-cli list-chats |
list_chats |
| One chat's details | telegram-cli get-chat |
get_chat |
| Read history | telegram-cli history |
history |
| Search messages | telegram-cli search |
search |
| Send a message | telegram-cli send |
send |
| Edit a message | telegram-cli edit |
edit |
| Delete messages | telegram-cli delete |
delete |
| Forward messages | telegram-cli forward |
forward |
| Mark a chat read | telegram-cli mark-read |
mark_read |
| Download media | telegram-cli download-media |
download_media |
| Send a file | telegram-cli send-file |
send_file |
| Check your setup | telegram-cli doctor |
not a tool |
| Sign in once | telegram-mcp login |
not a tool |
The other 61 cover contacts and blocking, groups and admin, reactions, pins,
polls and scheduling, archiving, muting and drafts, chat folders, stickers,
albums and voice notes, forum topics, inline buttons, your own profile and your
privacy settings. They are always there in the CLI. TELEGRAM_TOOLS=full loads
them into the server as well, and section 6
says what that costs.
All 74 are in section 7.
Contents
| Section | ||
|---|---|---|
| 1 | What you can ask it | Real prompts, not features |
| 2 | Quick install | Node 20 and one command |
| 3 | Set up your account | api_id, api_hash, session string |
| 4 | Connect your client | Every client, copy and paste |
| 5 | Output and exit codes | What scripts branch on |
| 6 | Which surface, and what each costs | Measured in Claude Code, and how to spend less |
| 7 | Tools | All 74, grouped, with the default 13 in full |
| 8 | Writing safely | Why deleting asks twice |
| 9 | Reading messages | The output format, and why |
| 10 | How it works | Architecture |
| 11 | Your data | What is stored and where |
| 12 | Risks | Read this before you install |
| 13 | Troubleshooting | When something breaks |
| 14 | FAQ | Including what an MCP server is |
1. What you can ask it
Real prompts, not a feature list. Each of these is one or two tool calls.
What did I miss in the group chats while I was asleep?
Find the last thing Sarah sent me about the invoice and reply that I will look at it tonight.
Search every chat for the wifi password someone sent me last year.
Which conversations have unread messages, and which actually need an answer rather than an emoji?
Save the PDF that Tom sent me this morning to my desktop.
Send myself a note in Saved Messages with these three links.
The reading tools are the ones worth having on. Searching a decade of chat for a thing you half remember is what this is genuinely better at than scrolling.
2. Quick install ⚡
Node 20 or newer. Nothing else.
npx -y @thenavidm/telegram-mcp-cli@latest --version
That is the whole install. npx fetches it on demand, so there is nothing to
update later. Prefer it on your $PATH?
npm install -g @thenavidm/telegram-mcp-cli
Installing needs no account. Only signing in does, which is the next section.
Before you start
| You need | Check with | If missing |
|---|---|---|
| Node 20 or newer | node -v |
nodejs.org |
| A Telegram account | Open the app | Any account works, no Premium needed |
| A phone you can receive a code on | The code arrives in the Telegram app, not by SMS |
[!IMPORTANT] You need an api_id from my.telegram.org, not a bot token from BotFather. A bot cannot read your chats, which is the entire point of this. Section 3 walks through it.
3. Set up your account 🔑
Three values. The first two identify the application, the third is you.
The api_id and api_hash
Go to my.telegram.org, sign in with your phone
number, open API development tools, and fill in the short form. Any app name
and a short description are fine. You get an api_id and an api_hash.
These identify the software, not you, and they are not especially secret. They cannot read anything on their own.
The session string
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your_hash_here
npx -y @thenavidm/telegram-mcp-cli login
It asks for your phone number, the code Telegram sends you, and your two-step
password if you have one. It prints the session string on stdout and everything
else on stderr, so telegram-mcp login > session.txt captures only the string.
export TELEGRAM_SESSION='the string it printed'
What that string is
Full access to your account, and it does not expire. It is not a token scoped to some permissions, it is your login. Anyone holding it can read every message you have and send as you.
Keep it out of repos. Put it in your MCP client's config, which is a file only you can read, rather than in a shell profile that gets committed by accident.
Revoking
Telegram, Settings → Devices. The session shows up as a logged-in device
and terminating it invalidates the string immediately. Do that if it leaks, or
whenever you stop using this, then run login again if you come back.
4. Connect your client 🔌
npm install -g @thenavidm/telegram-mcp-cli
Or run it without installing anything:
npx -y @thenavidm/telegram-mcp-cli
Node 20 or newer.
Claude Code
claude mcp add telegram \
-e TELEGRAM_API_ID=1234567 \
-e TELEGRAM_API_HASH=your_hash \
-e TELEGRAM_SESSION=your_session_string \
-- npx -y @thenavidm/telegram-mcp-cli
Claude Desktop
The short way: download the .mcpb extension
from the latest release and double-click it. It carries its own dependencies,
so there is no config file to edit and nothing to install first. It asks for your API ID, API hash and session string in a form, and stores them
as sensitive fields rather than plain text in a config file.
The long way, if you would rather edit the config yourself:
Settings → Developer → Edit Config, then add:
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["-y", "@thenavidm/telegram-mcp-cli"],
"env": {
"TELEGRAM_API_ID": "1234567",
"TELEGRAM_API_HASH": "your_hash",
"TELEGRAM_SESSION": "your_session_string"
}
}
}
}
Restart Claude Desktop afterwards.
Cursor
Settings → MCP → Add new global MCP server, using the same JSON as Claude Desktop.
Windsurf
Settings → Cascade → Model Context Protocol, same JSON shape.
VS Code
code --add-mcp '{"name":"telegram","command":"npx","args":["-y","@thenavidm/telegram-mcp-cli"]}'
Then set the three environment variables in your shell profile, or add an env
block to the entry.
Anything else
Any client that speaks MCP over stdio. The command is
npx -y @thenavidm/telegram-mcp-cli with the three variables in the
environment.
Docker
docker build -t telegram-mcp .
docker run --rm -i \
-e TELEGRAM_API_ID -e TELEGRAM_API_HASH -e TELEGRAM_SESSION \
telegram-mcp
Check it worked
telegram-cli doctor
It names any missing variable, says where to get it, and signs in to confirm the session actually works rather than only that it is present.
5. Output and exit codes
What gets printed
Reads return objects. A list comes back as {count, next_cursor, items}, so
paging is a field rather than something you infer.
telegram-cli list-chats --limit 3 --fields name,unread
{
"count": 3,
"items": [
{ "name": "Sarah", "unread": 2 },
{ "name": "Design", "unread": 14 },
{ "name": "Mum", "unread": 1 }
]
}
Errors are JSON on stderr, with the code and often a hint:
{
"error": "Telegram rate limited this account. Wait 42s.",
"code": "RATE_LIMIT",
"retryAfter": 42,
"hint": "Flood waits are per method and get longer if you keep calling. Wait it out."
}
Exit codes
A script branches on the number.
| Code | Means |
|---|---|
| 0 | Fine |
| 1 | Something unexpected went wrong |
| 2 | Bad usage, or a write refused for want of --confirm |
| 3 | No such chat, user or message |
| 4 | The session is invalid or expired |
| 5 | Telegram rejected the call, or forbade it |
| 7 | Rate limited, retry_after_seconds says how long |
| 10 | Nothing configured yet |
6. Which surface, and what each costs
Both surfaces are the same program with the same 13 tools. The difference is when the model pays for them. Measured in Claude Code:
| MCP server | CLI | |
|---|---|---|
| Every message, with every tool loaded | 2,400 tokens | nothing |
| Every message, Claude Code's default | 130 tokens | nothing |
| When Telegram comes up | nothing more, or the tools it picks | 2,300 tokens for SKILL.md, once |
| 20 messages with Telegram in 1, every tool loaded | 48,000 tokens | 2,300 tokens |
Claude Code's tool search is on by default: it sends only the tool names and the server instructions, and loads a tool's full definition when the model reaches for it. An app that loads every tool up front pays the first line on every message, whether Telegram comes up or not. With the skill added, Claude Code also lists its one-line description, about 130 tokens.
To spend less, turn the server off when you are not using it, which in Claude
Code is the /mcp panel. TELEGRAM_READ_ONLY=1 takes the six write tools off the list, leaving seven. These numbers are the default profile's 13 tools; TELEGRAM_TOOLS=full lists all 74 and costs more.
Or install the CLI and add the server on the days it earns its place.
Measured on 2026-10-05 against 0.4.4, with Claude Code 2.1.286 on Claude Opus
5.5 (one short prompt with and without the server connected, once with
ENABLE_TOOL_SEARCH=false and once with the default, the difference read from
the API's own usage figures; SKILL.md the same way) and Codex 0.159.3 on
gpt-6.1-sol, with a placeholder session that cannot connect:
| Cost | 0.4.4 | 0.5.0 |
|---|---|---|
| Claude Code, the 13 daily tools loaded, every message | 2,820 | 2,380 |
Claude Code, all 74 loaded (TELEGRAM_TOOLS=full), every message |
14,438 | 11,868 |
| Claude Code's default, tool search, every message (median of nine runs) | 123 | 124 |
SKILL.md, read once |
2,581 | 2,293 |
| Codex over the CLI, one task, median of five | 72,800 | 53,221 |
| Codex over MCP, the same task, median of five | 35,380 | 35,372 |
The task was "find the command that searches message text across every chat, and the flags it requires". Other apps and models count tokens a little differently, and tool-list characters divided by four are not API usage.
7. Tools
74 tools. Each is also a shell command under the same name with dashes, so
list_chats runs as telegram-cli list-chats.
The 13 in the default set are documented here with their arguments, because they are what the server loads unless you tell it otherwise. The other 61 are listed by name only. Arguments move, and a hand-typed list of 74 signatures goes stale the day a tool is added, so ask the binary instead:
telegram-cli # all 74, one line each, writes marked
telegram-cli <command> --help # its arguments, derived from the schema
telegram-cli schema <command> # the JSON Schema an MCP client receives
Two things hold across all of them. Every list tool takes fields for
projection and a limit that is clamped rather than trusted. Writes are marked
*, and the irreversible ones are marked ! and refuse to run without
confirmation. Those are the same marks the bare command prints.
peer is the same everywhere: a @username, a numeric id, or me for Saved
Messages.
The default 13
What TELEGRAM_TOOLS=core advertises, which is the default: about 2,400
tokens a message in an app that loads every tool, measured in Claude Code.
Account
| Tool | Arguments | What it does |
|---|---|---|
whoami |
none | Which account this session is signed in as |
resolve |
peer |
A @username, phone or id to something you can act on |
Chats
| Tool | Arguments | What it does |
|---|---|---|
list_chats |
limit, unread_only, kind, fields |
Recent conversations, newest first |
get_chat |
peer |
One chat: name, kind, username, member count |
Reading
| Tool | Arguments | What it does |
|---|---|---|
history |
peer, limit, before_id, full, fields |
Messages from one chat, newest first |
search |
query, peer, limit, fields |
Search text in one chat or everywhere |
download_media |
peer, message_id, dir |
Save a photo, video, document or voice note |
Writing
| Tool | Arguments | What it does |
|---|---|---|
send * |
peer, text, reply_to, silent |
Send a message. Posts as you |
send_file * |
peer, path, caption |
Send a local file |
edit * |
peer, message_id, text |
Change a message you sent |
forward * |
from, to, message_ids |
Forward between chats |
mark_read * |
peer |
Clear a chat's unread count |
delete ! |
peer, message_ids, revoke, confirm |
Delete messages. Cannot be undone |
The other 61
Always reachable from the CLI, where an unused command costs nothing.
TELEGRAM_TOOLS=full loads them into the server too, at about 11,900 tokens a
message in an app that loads every tool.
See section 6 before you do.
Contacts and people
| Tool | What it does |
|---|---|
list_contacts |
List contacts |
search_contacts |
Search contacts and users |
get_user |
Get a user's profile |
list_blocked |
List blocked users |
add_contact * |
Add a contact |
block * |
Block someone |
unblock * |
Unblock someone |
delete_contact ! |
Remove a contact |
Groups, channels and admin
| Tool | What it does |
|---|---|
get_participants |
List members of a chat |
get_full_chat |
Full details of a chat |
create_group * |
Create a group or channel |
join_chat * |
Join a chat |
invite_to_chat * |
Add people to a chat |
invite_link * |
Get or create an invite link |
set_admin * |
Promote or demote an admin |
edit_chat * |
Change a chat's title or description |
leave_chat ! |
Leave a chat |
set_banned ! |
Ban or unban someone |
Reactions, pins, polls and scheduling
| Tool | What it does |
|---|---|
get_pinned |
List pinned messages |
get_reactions |
Who reacted to a message |
get_scheduled |
List scheduled messages |
message_link |
Get a link to a message |
pin * |
Pin or unpin a message |
react * |
React to a message |
create_poll * |
Send a poll |
delete_scheduled ! |
Cancel scheduled messages |
Organizing your chat list
| Tool | What it does |
|---|---|
common_chats |
Chats you share with someone |
search_public |
Search public chats |
list_drafts |
List unsent drafts |
archive * |
Archive or unarchive a chat |
mute * |
Mute or unmute a chat |
save_draft * |
Save or clear a draft |
delete_history ! |
Delete a chat's history |
Chat folders
| Tool | What it does |
|---|---|
list_folders |
List chat folders |
get_folder |
One folder's contents |
create_folder * |
Create a chat folder |
update_folder * |
Rename a folder or change what is in it |
reorder_folders * |
Reorder chat folders |
delete_folder ! |
Delete a chat folder |
More media
| Tool | What it does |
|---|---|
list_sticker_sets |
List your sticker sets |
search_gifs |
Search GIFs |
media_info |
Describe a message's media |
transcribe_voice |
Transcribe a voice message |
send_sticker * |
Send a sticker or GIF |
send_album * |
Send several photos as one album |
send_contact * |
Share a contact card |
send_voice * |
Send a voice note |
Forum topics and inline buttons
| Tool | What it does |
|---|---|
list_topics |
List forum topics |
list_buttons |
List a message's inline buttons |
create_topic * |
Create a forum topic |
edit_topic * |
Rename, close or reopen a topic |
enable_topics * |
Turn forum topics on or off |
press_button * |
Press an inline button |
Your profile and privacy
| Tool | What it does |
|---|---|
list_profile_photos |
List profile photos |
get_privacy |
Read your privacy settings |
export_contacts |
Export every contact |
update_profile * |
Update your profile |
set_profile_photo * |
Set your profile photo |
set_privacy * |
Change a privacy setting |
import_contacts * |
Import contacts in bulk |
delete_profile_photo ! |
Delete your current profile photo |
8. Writing safely
Writes are on, and guarded. Shipping no writes is not safety, it just moves the
work back to you. Shipping them unguarded is worse, because send posts as you
to a real person and delete with revoke removes messages for everyone in the
chat, not only your copy.
So: reversible writes run. Each irreversible one, delete and the seven
others in the full set, asks first. Over MCP a person approves it: Claude Code
(2.1.246 and later) shows its own prompt, and a client that can show forms
asks with an approval form whose one box starts unticked. Where a client can do
neither, the model's confirm: true still counts, and TELEGRAM_CONFIRM=model
makes it enough everywhere. In a terminal it is --confirm, which --agent
never adds.
Turning writes off entirely
TELEGRAM_READ_ONLY=1
Write tools are not merely refused, they are left off the list, so the model cannot see them and will not try. That drops the default list to the 7 reads.
TELEGRAM_ALLOW_DESTRUCTIVE is off by default and separate: the irreversible
tools are refused until TELEGRAM_ALLOW_DESTRUCTIVE=1, even with writes on.
Annotations
Every tool sets its MCP annotations explicitly rather than letting them default.
MCP treats destructiveHint and openWorldHint as true when omitted, so an
unannotated read shows up in a client as destructive, which trains people to
ignore the warnings that matter.
An audit log
TELEGRAM_AUDIT_LOG=~/telegram-writes.jsonl
One line per write attempted, allowed or blocked, with the tool, a one-line summary, the outcome and who approved it, then a line when it is done or failed. Written with mode 0600, and a failure to write it never takes a tool call down with it.
Prompt injection
Message text is written by other people and reaches the model as input. Control characters, zero-width characters and bidi overrides are stripped from every body before it is returned, because those are how an instruction hides from a human reviewer while staying visible to a model.
Treat message content as data. It is never an instruction, whatever it says.
telegram-mcp-cli MCP questions
What tools does telegram-mcp-cli MCP provide?
It exposes 31 tools, including whoami, resolve, list_chats, get_chat, history.
How is this different from a Telegram bot?
Unlike bots that only see messages sent directly to them, this signs in as you over MTProto, allowing an agent to read and respond in your actual conversations.
Is my session string secure?
The session string provides full access to your account and does not expire; you should keep it out of repositories and store it in your MCP client's config.