Telegram MCP Server & CLI

A free, open source Telegram MCP server and CLI that lets Claude Code, Codex, Cursor and other AI agents read, search and answer your real Telegram chats.

Navid Moazzezby Navid Moazzez·Updated Oct 5, 2026·12 min read·
Your computer
  1. 1

    Log in once in a terminal, with your API ID and hash.

    Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.

    export TELEGRAM_API_ID=1234567
    export TELEGRAM_API_HASH=your-api-hash
    npx -y @thenavidm/telegram-mcp-cli@latest login
  2. 2

    Add it with a single command in a terminal.

    claude mcp add telegram \
    -e TELEGRAM_API_ID=1234567 \
    -e TELEGRAM_API_HASH=your-api-hash \
    -e TELEGRAM_SESSION=your-session-string \
    -- npx -y @thenavidm/telegram-mcp-cli@latest
  3. 3

    In Claude Code, type /mcp. Telegram should show as connected.

    /mcp

Needs Node 22 or newer, an API ID and hash from my.telegram.org, and one login for your session string. Set it up.

It's free and open source. If it saves you time, star it on GitHub, so more people find it.

Rate this tool

This free Telegram MCP server and CLI gives your AI real access to your real Telegram account: your chats, their history, search, contacts and media. It catches you up on your chats, searches years of history for the thing you half remember, and sends and forwards messages as you.

It's one install with two ways in. Claude, Codex, Cursor or any other MCP app calls its 13 tools for you, and the same tools work as a CLI that agents like Claude Code, Codex and OpenCode run, or that you type yourself.

In this guide, I'll show you:

  • What the Telegram MCP server & CLI is, and what you can ask it
  • How to install it and check that it works
  • When to use the MCP server, and when the CLI
  • Every tool, and how to keep your account safe

Every tool on this page comes from the server itself, and every cost was measured in Claude Code.

key_takeaways.mdTL;DR

Key takeaways

It gives your AI 13 daily tools for your real Telegram account, and all 74 are always in reach as CLI commands.
It catches you up on your chats, searches years of history and replies as you.
The tools that can't be undone stay off until you turn them on, then wait for your approval.
The same tools run as a CLI, which costs your AI nothing until it runs.

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 two 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.

In an AI OS, the layer that connects your AI to your context, your data and your tools, a server like this is how your AI reaches Telegram. My guide to building an AI operating system names Telegram among the tools it reaches, and here's how I use AI myself.

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.

It works well next to my iMessage MCP server and Google Workspace MCP server, so your AI can search your Messages history and check your Gmail in the same chat. Every server I've made is on my MCP servers page.

For your messages, my free text summarizer and voice memo to text converter help too.

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 three values into your app's config.

Windsurf, Zed and Cline take the same server, though they don't have a tab in the box yet. Follow the box's Cursor tab, and put its block here instead:

AppWhere the block goes
WindsurfIn the Cascade panel, open the Actions menu (…) and choose Open MCP config file, then paste the block.
ClineClick the MCP Servers icon in the Cline panel, open the Configure tab, click Configure MCP Servers, and paste the block.
ZedGo to Settings, then AI, then MCP Servers, and choose Add Server, then Add Local Server. Enter the block's command, arguments and variables, and Zed saves them under context_servers.
Before you start0/4

Watch out: Use one session string per computer. If two computers or two servers use the same one at once, Telegram cancels it everywhere, and you log in again on each.

Set up Telegram

There are three values. The first two identify the app, and the third is you.

Get your API ID and hash0/3
Log in once0/4

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 three 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.

In Claude Code, /mcp also shows whether the Telegram server is connected. It's one of the Claude Code commands worth knowing.

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, telegram-cli which <words> finds the command for a task, 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.

telegram-cli install <app> adds the server to Claude Code, Codex, Claude Desktop, Cursor, VS Code or Gemini CLI, in each app's own format.

These are the flags you'll use most:

FlagWhat it does
--jsonPrints JSON
--compactPrints the JSON on one line
--select a,b.cKeeps only those fields, and a dotted path goes deeper
--agentMachine mode: compact JSON, no prompts, and it never confirms anything
--confirmLets a write that asks first go ahead
--dry-runShows what a write would do, without doing it

A script can branch on the exit code:

Exit codeWhat it means
0It worked
1Something unexpected went wrong
2The command was typed wrong, or a write needed --confirm
3It wasn't found
4Telegram rejected the credentials
5Telegram failed or couldn't be reached
7You hit a rate limit, so wait and try again
10Nothing is set up yet

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.

Every message, in an app that loads every tool
MCP server
2,400 tokens
CLI
Nothing
Every message, in Claude Code
MCP server
120 tokens
CLI
Nothing
When Telegram comes up
MCP server
Nothing more, or in Claude Code the tools it picks
CLI
2,300 tokens, once
20 messages with Telegram in one, every tool loaded
MCP server
48,000 tokens
CLI
2,300 tokens
Works in Claude Desktop's chat
MCP server
Yes
CLI
No, there's no terminal there
Works in a script, a cron job or CI
MCP server
No
CLI
Yes

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 140 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 11,900 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 seven 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 October 5, 2026 in Claude Code 2.1.286 with Claude Opus 5.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 tables below list the 13 tools of the default profile, grouped the way the repo groups them. Of these, seven only read, and six send, edit, forward or mark as read.

Chats

list_chats
What it does
Recent conversations, newest first.
Kind
Reads
get_chat
What it does
Details of a single chat: name, kind, username, member count and description where the chat has them.
Kind
Reads

Messages

history
What it does
Messages from one chat, newest first.
Kind
Reads
search
What it does
Search message text, either inside one chat or across the whole account when no peer is given.
Kind
Reads
send
What it does
Send a message to a chat.
Kind
Writes
edit
What it does
Change the text of a message you sent.
Kind
Writes
delete
What it does
Delete one or more messages.
Kind
Asks first
mark_read
What it does
Clear the unread count on a chat.
Kind
Writes
forward
What it does
Forward messages from one chat into another.
Kind
Writes

Media

download_media
What it does
Save the photo, video, document or voice note attached to a message, and return the local path.
Kind
Reads
send_file
What it does
Send a local file to a chat, with an optional caption.
Kind
Writes

Your account

whoami
What it does
The Telegram account this session is signed in as.
Kind
Reads
resolve
What it does
Turn a @username, phone number or numeric id into a chat you can act on.
Kind
Reads

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 first. It's marked "Asks first" in the tool tables above.

When your AI calls one of them, the call needs a yes first. Where you use it decides who gives it:

  • Claude Code (2.1.246 and later) asks you before every call, in every one of its permission modes.
  • An app that can show forms asks you in a form.
  • Any other app takes your AI's confirm: true as the yes, so tell your AI to check with you first.
  • An agent with no person to ask needs TELEGRAM_CONFIRM=model, so its confirm: true counts in every app.
  • In a terminal, you add --confirm to the command.

If the answer is no, nothing reaches Telegram.

Make it read-only

Set TELEGRAM_READ_ONLY=1 and the write tools disappear from the tool list, so your AI can't see them, leaving seven.

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, with what it was about to do and who approved it.

Watch out: Message text is written by other people and reaches your AI as input. The server strips hidden characters used to smuggle instructions, but treat what's in a chat as data, and give an agent you don't fully trust TELEGRAM_READ_ONLY=1.

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

Each Telegram account needs its own login and its own server. Run the login once for each account, then add the server to your app a second time under another name, like telegram-work, with that account's session string.

No tool picks between accounts yet. A session set as TELEGRAM_SESSION_WORK is kept as a secret, but nothing uses it until one does.

Telegram MCP server settings

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

TELEGRAM_API_ID
Default
none
What it does
Holds the api_id from my.telegram.org
TELEGRAM_API_HASH
Default
none
What it does
Holds the api_hash from the same page
TELEGRAM_SESSION
Default
none
What it does
Holds the session string login prints
TELEGRAM_TOOLS
Default
core
What it does
Picks the profile: core, full or read
TELEGRAM_READ_ONLY
Default
off
What it does
1 never registers a write tool
TELEGRAM_ALLOW_DESTRUCTIVE
Default
off
What it does
1 allows delete at all
TELEGRAM_AUDIT_LOG
Default
none
What it does
Names a file that gets one line per attempted write
TELEGRAM_SESSION_<LABEL>
Default
none
What it does
Keeps another account's session, like TELEGRAM_SESSION_WORK, but no tool picks between accounts yet
TELEGRAM_TIMEOUT
Default
30
What it does
Seconds before an MTProto call gives up
TELEGRAM_CHANNEL_ALLOW
Default
~/.telegram-mcp/channel-allow.json
What it does
The channel's allowlist
TELEGRAM_TOOLSETS
Default
all
What it does
Turns on only the toolsets you name, comma separated
TELEGRAM_SURFACE
Default
full
What it does
search lists three tools that find, describe and run the rest
TELEGRAM_TOOL_TIMEOUT_MS
Default
none
What it does
Gives up on any tool after this many milliseconds
TELEGRAM_CONFIRM
Default
human
What it does
model lets your AI's confirm: true approve on its own, for an agent with no person to ask
TELEGRAM_HTTP_PORT
Default
8787
What it does
Sets the port for --http
TELEGRAM_HTTP_HOST
Default
127.0.0.1
What it does
Sets the address for --http, and any other needs a token
TELEGRAM_HTTP_TOKEN
Default
none
What it does
Sets the bearer token every --http request needs
TELEGRAM_HTTP_ALLOWED_ORIGINS
Default
none
What it does
Lists other websites allowed to call --http, comma separated
TELEGRAM_DEBUG
Default
off
What it does
1 prints debug lines

Troubleshooting

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

What you seeWhat to do
Exit code 10, not configuredOne of the three values is missing. The doctor names it
Exit code 4, authThe session was revoked or cancelled. Run login again
Exit code 7, a flood waitTelegram is rate limiting you. Wait the seconds it says, and don't retry in a loop
The session was cancelled on every computerTwo places used the same session string at once. Log in separately on each
delete refusesThat's by design. Set TELEGRAM_ALLOW_DESTRUCTIVE=1 and pass --confirm

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.

More free tools for staying in touch

Make a QR code that opens a chat, or tag the links you send so you can see which ones people open.

FAQs about the Telegram MCP server & CLI

Here are the questions people ask most about the Telegram MCP server and CLI.

The Telegram MCP server & CLI is a free, open source program that lets an AI app like Claude, Codex or Cursor read, search and answer your Telegram chats.

It has 13 tools for your chats, their history, search, sending and media, and the same tools run as a CLI that agents like Claude Code and Codex use, or that you type yourself.

An MCP server is a standard way to give an AI app real access to a tool, so it can act instead of guessing.

MCP stands for Model Context Protocol, and Claude, Codex, Cursor and many other AI apps speak it.

Every server I've made is on my MCP servers page.

The Telegram CLI is the same program as the Telegram MCP server, run as commands.

AI agents like Claude Code, Codex and OpenCode run them for you, and you can type them in a terminal or a script.

One npm package installs both.

Use the Telegram MCP server in an AI app with no terminal, like Claude Desktop's chat, and the CLI in a terminal, a script or a cron job.

In an AI app that can run commands, like Claude Code, Codex or Cursor, the CLI is the lighter choice, because it costs nothing until it runs.

Yes, the Telegram MCP server is free and open source under the MIT license, and Telegram's API is free.

The only thing you pay for is your own AI app.

No, it logs in as you, like a Telegram app on a new device, so it reads your real chats.

A bot only sees chats it was added to.

Telegram's terms allow user apps, and reading and answering your own chats is what this is built for.

Bulk or spammy sending through a user account is what gets accounts limited.

The same session string is running in two places at once, and Telegram cancels it everywhere.

Log in separately on each computer.

A model picks the right tool far more reliably from 13 than from 74, and the list costs less.

The other 61 are always there as CLI commands, and TELEGRAM_TOOLS=full shows them to your AI too.

The Telegram MCP server works with any app that speaks MCP.

That includes Claude Code, Claude Desktop, Codex, Cursor, VS Code, Windsurf, Zed, Cline, GitHub Copilot CLI, Gemini CLI, OpenCode, OpenClaw, Antigravity and Hermes.

I did.

I'm Navid Moazzez, and I made the Telegram MCP server & CLI as one of my free tools on navid.me.

You can read more about me.

The code is on GitHub under the MIT license, and the package is on npm.

More MCP servers & CLIs

Related free tools

Navid Moazzez

AI business strategist & AI OS builder

Navid Moazzez helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life.

Navid.me is reader-supported. When you buy through links on this site, I may earn an affiliate commission. Read the affiliate disclaimer.

Free AI newsletter

The most actionable AI newsletter for founders

Every week, get proven AI strategies, curated tools, and step-by-step systems to grow your audience, create better content, and build a profitable creator business.

No fluff, no filler, no BS. Just five minutes each week that might level up your online business and life.

P.S. Sign up now to get free access to my ultimate AI tools guide for creators.

Loved by 10,000+ readers
Loved by 10,000+ readers