Telegram AI CLI MCP

Name: Telegram AI CLI MCP
Author: stufently

by stufentlyversion 0.1.3i★ –iRuns on your computer

Registry nameio.github.stufently/telegram-ai-cli-mcp

Install

Overview

Description from the maker (original English)

Read a personal Telegram account over MTProto; every write is a plan a human applies.

PopNx MCP’s three pillars

These three are never merged into one score: opinions, measurements and popularity are different things.

User voiceiNo reviews yetReviews open together with accounts in a later step
Our basic checksi1 of 1 passedChecked from public information; code not scanned yet
UsageiNot measured yet★ –

What you can do with it

We have not written a plain-language summary for this one yet. Below are the facts we read from the registry.

Connection: Runs on your computer
Transport: stdio
Category: Chat & email

Install

Pick the AI app you use, then copy the settings.

Before you install

Basic checks: 1 of 1 passed
Runs on your computer with your user’s permissions (files, network, apps).
You fill in yourself: TGAI_PROFILE, TGAI_CONFIG

You need

PyPIPython’s uv installed (for the uvx command)

Which app do you use?

ClaudeClaude CodeCursorVS CodeChatGPT

Pick your app above. We remember it, so next time the button says “Install in …”.

Open Claude Desktop → Settings → Developer → Edit Config, and paste this into claude_desktop_config.json

{
  "mcpServers": {
    "telegram-ai-cli": {
      "command": "uvx",
      "args": [
        "telegram-ai-cli-mcp",
        "mcp"
      ],
      "env": {
        "TGAI_PROFILE": "your-value",
        "TGAI_CONFIG": "your-value"
      }
    }
  }
}

Run this in your terminal

claude mcp add telegram-ai-cli --env TGAI_PROFILE=your-value --env TGAI_CONFIG=your-value -- uvx telegram-ai-cli-mcp mcp

Fill in the empty values before running it.

Open in Cursor

Or copy the settings yourself

Paste into .cursor/mcp.json in your project, or ~/.cursor/mcp.json

{
  "mcpServers": {
    "telegram-ai-cli": {
      "command": "uvx",
      "args": [
        "telegram-ai-cli-mcp",
        "mcp"
      ],
      "env": {
        "TGAI_PROFILE": "your-value",
        "TGAI_CONFIG": "your-value"
      }
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

Open in VS Code

Or copy the settings yourself

Paste into .vscode/mcp.json in your project

{
  "servers": {
    "telegram-ai-cli": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "telegram-ai-cli-mcp",
        "mcp"
      ],
      "env": {
        "TGAI_PROFILE": "your-value",
        "TGAI_CONFIG": "your-value"
      }
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

This one runs on your computer, and ChatGPT can only connect to servers on the internet. Pick another app.

Your choice stays on this device in a cookie; no account needed.

Values you fill in

TGAI_PROFILE env
readonly (default) or plan: plan lets the agent prepare plans, never apply them
TGAI_CONFIG env
Path to tgai.yaml if not ~/.config/telegram-ai-cli-mcp/tgai.yaml

These settings are generated from the maker’s registry entry. If the README says otherwise, follow the README.

What it can do

Runs on your computer; the tool list appears in your AI app after you install it.

Basic checksi

We check information anyone can see; we have not read the code. Checks that do not apply are left out of the count. · Checked Nov 7, 2026

✓ Pass
Maker matches the repo
The registry name was verified with the GitHub account stufently, which owns the repo
… Not checked yet
Still maintained
We have not read this repo from GitHub yet
… Not checked yet
Has a licence
We have not read this repo from GitHub yet
– Not applicable
Endpoint responds
This one runs on your computer; there is no internet endpoint
– Not applicable
Sign-in with OAuth
Runs on your computer and uses local settings instead
… Not checked yet
No hidden instructions in tool descriptions
Runs on your computer; we can only read tool lists from internet endpoints

Compared with others in Chat & emaili

More stars than 0% of the other 1783 servers in this category
Published to the registry more recently than 54% of the other 1783 servers in this category
Basic checks equal to or better than 100% of the other 1783 servers in this category

Compared with every active server in this category in the registry. Stars count only when the publisher owns the repo.

Common questions

Is Telegram AI CLI MCP safe?

It passed 1 of 1 applicable basic checks. We have not read the code. Before adding a key or token, see what access the server asks for and use a key with only the permissions you need.

What keys or codes does it need?

The registry does not list a required key, though some servers ask you to sign in on first use.

Does it run on my computer or in the cloud?

It runs on your computer. Your AI app starts it when needed, and data does not pass through the maker’s servers (unless it calls an online service itself).

Is it still maintained?

The GitHub repo last changed –, and the latest version (0.1.3) reached the registry 24 days ago.

Which apps can use it?

Apps that support MCP, such as Claude Desktop, Claude Code, Cursor and VS Code. You also need Python (uv) on your computer.

What can I use instead?

In the same category: Vexa, emailmd, MCP WhatsApp Cloud

Alternatives

Servers in the same category from other makers, sorted by stars.

Reading a card:★ GitHub starsiThree pillars: reviews · checks · usageiUpdated = latest version published to the registryi

Vexa

by Vexa-ai

Meeting bot and transcripts for Google Meet, Teams and Zoom. Live or after, speakers labelled.

Runs in the cloud★ 2,949Apache-2.0Updated 2 months ago

Install

emailmd

by anypost

Render markdown into email-safe HTML, lint drafts for deliverability problems, and preview emails.

Computer or cloud★ 1,385MITUpdated 31 days ago

Install

MCP WhatsApp Cloud

by codespar

MCP server for WhatsApp Cloud API (Meta) — messages, media, and templates via Graph API

Runs on your computer★ 277MITUpdated 5 months ago

Install

README from the maker

Open the README

Copied from the maker’s repo as written. PopNx MCP has not reviewed or endorsed it. HTML, images and scripts are removed. Links lead off this site.

telegram-ai-cli-mcp — CLI and MCP server for AI agents on a personal Telegram account

telegram-ai-cli-mcp is a CLI and MCP server, built from one Python codebase, for automating a personal Telegram account over MTProto. It gives Claude Code, Claude Desktop, Codex, Cursor and other MCP clients task-shaped access to Telegram — read chats, search messages, resolve who a username belongs to, check who's in a group — while anything that changes something on Telegram (sending a message, joining a chat, deleting, promoting an admin) goes through an explicit plan-and-apply step instead of running the moment a model asks for it.

It is for people who want an AI agent to have a hand on their own Telegram — triaging messages, drafting replies, watching a chat for something specific — without giving that agent the standing ability to send, join or invite on its own.

This automates a personal Telegram account (MTProto), not a bot account (Bot API). Telegram can limit or permanently ban accounts it judges to be running abusive automation — mass joins, high-volume sends, scraping members. Using this tool against your own account is at your own risk; see Why not another MTProto wrapper for why a personal account behaves differently from a bot in the first place.

Status: 0.1.x, on [PyPI](https://pypi.org/project/telegram-ai-cli-mcp/). Before 1.0.0 a breaking change can come in any 0.x release, and the changelog names it; deliberate non-goals and accepted local-boundary risks are recorded in docs/product-boundaries.md.

tg-ai account add --label work

tg-ai account login --label work tg-ai chats --search "team" tg-ai chat read --chat 123456789 --limit 50 tg-ai message send --chat 123456789 --text "On my way" # writes a plan, sends nothing tg-ai plan apply 4f0f8a2b9c7e1d3a5b6c7d8e9f0a1b2c tg-ai mcp

Why not another MTProto wrapper

Handing a model raw Telethon or a thin MTProto wrapper hands it Telegram's sharp edges too:

Usernames are not stable identifiers. @someone can change hands; a tool that plans against a handle and sends against the same handle later can address a different person than the one it was approved for. Every plan here resolves a target to a numeric peer id once, and re-checks that id — not the handle — at apply time.
`FloodWaitError` is not something to swallow. Telethon's default flood_sleep_threshold sleeps and retries a failed call automatically, which is exactly the wrong behavior for a plan-and-apply tool: an automatic retry after a timeout is how one intended send becomes two. This project turns that default off and drives retries itself.
Reading a chat is not free of side effects by default. Most Telegram clients move the read pointer the moment a dialog is opened. A tool an agent can call to "just look" has to guarantee that looking never marks the other person's messages read — that's asserted by a dedicated test here, not left to documentation.
`noforwards` (protected content) is enforced by Telegram, not by your client. A chat marked content-protected refuses forwards at the server (CHAT_FORWARDS_RESTRICTED), and no client gets round that — so message.forward out of one fails, and this project's job is only to say so in those words instead of surfacing a Telethon class name. Downloading is not blocked here: Telegram asks *clients* to stop people saving protected attachments, which the official apps honour and a raw MTProto library does not — Telethon saves the file like any other, and this project adds no guard of its own rather than pretending to one. That means re-posting the bytes as a fresh upload is possible — it is media fetch followed by message send-file, two plans somebody approves separately — and there is deliberately no one-step feature for it, because a message you post yourself is your own act and should read like one.
A revoked session does not fail cleanly. Terminating a session from the phone's Settings → Devices doesn't raise a friendly "logged out" error on the next call — it raises AuthKeyDuplicatedError or SessionRevokedError, and a client that retries every disconnect the same way ends up looping against a session that is never coming back.
A user account is not a bot account. Bot API bots are rate-limited and sandboxed by Telegram on purpose, and can't read history the way a member can. A personal account can do far more — which is also why Telegram polices unusual activity on it more aggressively: mass joins, high-volume sends and member scraping draw limits and bans, not just error codes.
`tdata` is Telegram Desktop's own undocumented on-disk session format, not something Telegram publishes a schema for. Getting an import wrong doesn't fail loudly — see the tdata warning under Configure.

What it does

Command	Answers
`tg-ai fleet`	Which accounts are configured, authorized, expired or locked right now
`tg-ai chats`	Which chats exist, and what their chat id is (search by title)
`tg-ai chat read`	What was said in a chat — paged with `--before-id`, filtered to one forum topic with `--topic-id`, with media metadata
`tg-ai chat topics`	Which topics a forum supergroup has, and where the unread messages are
`tg-ai inbox`	What's waiting for a reply right now, across every configured account
`tg-ai watch`	Wait for the next incoming message instead of polling for it — a burst of fast replies comes back as one answer, and the wait is capped
`tg-ai search`	Which messages match a phrase, and where — with `--context N`, the messages either side of each match
`tg-ai whois`	Who a `@username`, numeric id or invite resolves to; for channels, the "message the admins" Direct Messages chat — its name, and an id you can read or send to without joining anything
`tg-ai chat members`	Who's in a chat, and who administers it
`tg-ai media fetch`	Save a message's photo, video or document to a server-controlled path
`tg-ai media transcribe`	Turn a voice message into text — Whisper in an optional container, on your own machine, with the network switched off
`tg-ai archive sync`	Copy one named chat into a local SQLite archive, resuming where the last run stopped
`tg-ai archive search`	Search that archive offline — substring or regular expression, by sender, by date — with no Telegram request at all
`tg-ai archive status`	Which chats are archived, how many messages, and when each was last synced
`tg-ai archive forget`	Erase one chat, and every message of it, from the local archive
`tg-ai drafts`	What was started and never sent, and in which chat
`tg-ai scheduled`	What is queued to be sent to a chat later, and when
`tg-ai account sessions`	Which devices and apps this account is signed in on — and whether one of them isn't yours
`tg-ai message send` / `message send-file` / `chat join` / `chat promote` / …	Validate and save an intent — send a message or a file, edit, delete, forward, join, leave, create a group, invite, promote, change the profile — as a plan. Nothing goes out yet
`tg-ai chat ban` / `unban` / `kick` / `restrict` / `demote`	Moderation, planned the same way: one member per plan, and the preview says who, where, which rights and for how long
`tg-ai message schedule`	Queue a message for an exact time — or for when the other person is next online — as a plan. Once applied it sits in Telegram's own scheduled queue, visible and cancellable in the app
`tg-ai chat archive` / `chat mute`	Put a chat in Archived, or silence it for a while or indefinitely — settings only this account can see, planned like every other write
`tg-ai folder add`	Put a chat into one of the folders the account already has. Telegram replaces a folder wholesale when it is edited, so everything already in it is preserved verbatim — including the chats this configuration may not list
`tg-ai plan list` / `plan show`	See what's waiting for a decision, and exactly what applying it would do
`tg-ai plan apply`	Carry out exactly what a saved plan describes
`tg-ai plan reject`	Decline a pending plan
`tg-ai daemon serve --account`	Hold one account open so several local callers share it instead of the second one being refused
`tg-ai mcp` / `tg-ai mcp --http`	Serve MCP over stdio, or over loopback HTTP with a mandatory bearer token

Safety

Read operations run immediately. Nothing else does — every operation that changes something on Telegram is a two-step plan, then apply.

Caller	Read	Plan	Apply
CLI, a person at a terminal	immediate	`tg-ai message send …` (each write operation is its own command; it saves a plan and prints the id)	`tg-ai plan apply`
MCP client with no shell access (Claude Desktop, most IDE/editor integrations)	immediate	`telegram_plan_` tool — only under `profile: plan`; the default `readonly` profile does not publish plan tools at all	not reachable — there is no MCP tool that applies a plan
MCP client that also has its own shell (Claude Code, Codex, and similar coding agents)	immediate	`telegram_plan_` tool — only under `profile: plan`	can run `tg-ai plan apply` itself, through its own shell — see the note below

Read-only by default, writing by explicit opt-in. A fresh install runs the readonly profile, and its MCP tool list contains no telegram_plan_* tool: a client sees the read tools and four local tools that write only into configured directories on this machine (see MCP tools), and a plan tool called by name anyway is refused with FORBIDDEN_BY_PROFILE before anything runs. Publishing the plan tools takes profile: plan in the config or TGAI_PROFILE=plan in the client's environment — and even then nothing is sent until a person runs tg-ai plan apply.

A write command never sends anything by itself — it records a plan and tells you how to carry it out:

$ tg-ai message send --chat 987654321 --text "Meeting moved to 3pm"

{ "plan_id": "4f0f8a2b9c7e1d3a5b6c7d8e9f0a1b2c", "operation": "message.send", "summary": "send to Marketing Team (group, 987654321): \"Meeting moved to 3pm\"", "state": "pending", "next": "tg-ai plan apply 4f0f8a2b9c7e1d3a5b6c7d8e9f0a1b2c" }

tg-ai plan show prints exactly what applying it would do — every field already passed through the same sanitizer that protects the terminal from a hostile chat title or message body (see render.py) — and only tg-ai plan apply (with a confirmation prompt, or --yes to skip it) actually carries it out.

The honest limit of this design, stated plainly: there is no MCP tool that applies a plan, on purpose — a confirmation an agent can send over MCP is a confirmation prompt injection can send. But that boundary is a property of the *transport*, not of the agent. An MCP client that has its own shell — Claude Code, Codex, and comparable coding agents — can simply run tg-ai plan apply as a shell command, the same as a person would. Nothing in this project detects or blocks that, because nothing at the process level can tell "the person typed this command" apart from "the agent typed this command" once both share a terminal.

For tha

Only the beginning is shown; read the rest in the repo

Telegram AI CLI MCP

Overview

PopNx MCP’s three pillars

What you can do with it

Install

Before you install

Values you fill in

What it can do

Basic checksi

Maker matches the repo

Still maintained

Has a licence

Endpoint responds

Sign-in with OAuth

No hidden instructions in tool descriptions

Compared with others in Chat & emaili

Common questions

Alternatives

Vexa

emailmd

MCP WhatsApp Cloud

README from the maker

telegram-ai-cli-mcp — CLI and MCP server for AI agents on a personal Telegram account

Why not another MTProto wrapper

What it does

Safety