Telegram MCP Server & CLI

What is the Telegram MCP server & CLI?

The Telegram MCP server & CLI is a free, open source program that lets AI agents read, search and answer your Telegram chats for you, in 2 ways. The MCP server is what an AI app like Claude, Codex or Cursor connects to, through MCP (Model Context Protocol), the open standard AI apps use to call outside tools.

You ask in plain language. Your AI picks the right tool, and the server makes the call to Telegram's own servers, logged in as you.

The CLI is the same program as commands. telegram-cli search --query "wifi password" runs the same code your AI runs when you ask for something someone sent you, whether an agent like Claude Code runs it or you do.

What can you ask it?

Once it's set up, you ask the way you'd ask an assistant. These are real prompts it handles:

Try asking
What did I miss in the group chats while I was asleep?
Search every chat for the wifi password someone sent me last year.
Find the last thing Sarah sent me about the invoice and reply that I'll look tonight.
Which conversations have unread messages, and which actually need an answer?
Save the PDF that Tom sent me this morning to my desktop.
Send myself a note in Saved Messages with these three links.

The second one shows why this is useful. Searching a decade of chats for something you half remember is what this does better than scrolling.

How to install the Telegram MCP server

Pick your app in the box at the top of this page. You log in once to get your session string, then paste 3 values into your app's config.

Set up Telegram

There are 3 values. The first 2 identify the app, and the third is you.

The session string is your login, not a limited token. Anyone holding it can read every chat and send as you, so keep it in your app's config and out of anything you share. To revoke it, end the session in Telegram under Settings, then Devices.

Check that it works

Run the doctor. It checks the 3 values, connects, and says which account it's signed in as.

npx -y @thenavidm/telegram-mcp-cli doctor

If the server starts and then exits, the session string is usually wrong or was revoked. Run login again.

Use the Telegram CLI

The CLI is the same 13 tools as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal or a script.

Every tool name becomes a command with dashes, so list_chats runs as telegram-cli list-chats.

npm install -g @thenavidm/telegram-mcp-cli
telegram-cli
telegram-cli list-chats --limit 10
telegram-cli search --query "invoice"
telegram-cli history --peer me --limit 5

The bare telegram-cli lists every command, and telegram-cli <command> --help shows what a command takes. Deleting messages asks for --confirm first, and it's off entirely until you set TELEGRAM_ALLOW_DESTRUCTIVE=1.

These flags work on every command:

A script can branch on the exit code:

MCP server or CLI: which one?

Both are the same program with the same 13 tools. The difference is when your AI pays for them, in the tokens it reads.

An app that loads every tool up front sends the full list with every message, whether you mention Telegram or not. Claude Code doesn't by default: its tool search sends only the tool names and the server's instructions, and loads a tool's full definition when your AI reaches for it.

The CLI costs nothing until Telegram comes up. Then your agent reads its skill file once and runs the commands it needs. With the skill added, Claude Code also lists its one-line description with every message, about 130 tokens.

When the whole conversation is about Telegram, the gap closes. Then the MCP server is the better experience, because you ask in plain language and your AI never has to look up a command.

How to spend less

In Claude Code, leave tool search on, which it is unless you've set ENABLE_TOOL_SEARCH=false.

Keep the default profile. TELEGRAM_TOOLS=full adds the other 61 tools to your AI's list and costs about 14,400 tokens a message in an app that loads every tool. The CLI reaches all 74 either way. TELEGRAM_READ_ONLY=1 cuts the list to the 7 reading tools.

Or install the CLI and connect the server later, on the days it earns its place. Every tool stays in reach, and the standing cost drops to nothing.

Every number here was measured on September 27, 2026 in Claude Code 2.1.257 with Claude Opus 5. It's the same one-line prompt with and without the server connected, once with tool search off so every tool loads, and once with Claude Code's default. The skill was measured the same way, and other apps and models count tokens a little differently.

13 tools by default, 74 in reach

The server shows your AI 13 tools: the ones that get used, for reading, searching, sending and media. A model picks the right tool far more reliably from 13 than from 74, and the list costs much less.

The other 61, for contacts, groups, admin, folders, polls, reactions and privacy, are always there as CLI commands, where an unused one costs nothing. Set TELEGRAM_TOOLS=full to show them all to your AI too, or read for the reading tools only.

Every Telegram tool

The 13 tools of the default profile, grouped the way the repo groups them. 7 only read, and 6 send, edit, forward or mark as read.

Chats

Messages

Media

Your account

Is the Telegram MCP server safe?

Writes work from the start, because answering your chats is the point. A message goes to a real person as you, so read what your AI is about to send.

delete can remove a message for everyone in the chat, so it's off until you set TELEGRAM_ALLOW_DESTRUCTIVE=1, and then it asks for a confirm check, marked Asks first in the tool tables above.

Make it read-only

Set TELEGRAM_READ_ONLY=1 and the write tools are never registered, so your AI can't see them, leaving 7.

Keep a log of every write

Set TELEGRAM_AUDIT_LOG to a file path. The server writes one line per attempted write, allowed or blocked.

Your data

There's no server of ours in between. The only calls go to Telegram's own servers, and there's no account to create and no tracking.

The session string lives wherever you put it, and the server never writes it to disk. Message text is held in memory for one call. Media goes where you ask, and the audit log is written only when you set TELEGRAM_AUDIT_LOG.

Several accounts

Add a second account as TELEGRAM_SESSION_WORK, or any label you like, with its own session string from its own login. Every tool then takes account to pick one.

Telegram MCP server settings

The first 3 are required. The rest are optional, as environment variables in your app's config.

Troubleshooting

Run the doctor first. It names the step that failed and the fix.

If the server doesn't show up in your app at all, run the command your app runs, in a terminal, and read the error.