Telegram AI CLI MCP

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

Safety

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

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