telegram-ai-cli-mcp

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

<!-- mcp-name: io.github.stufently/telegram-ai-cli-mcp -->

[![CI](https://github.com/stufently/telegram-ai-cli-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/stufently/telegram-ai-cli-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue.svg)](#compatibility)
[![MCP](https://img.shields.io/badge/MCP-stdio-green.svg)](#mcp-tools)

**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](#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](CHANGELOG.md) names it; deliberate non-goals and accepted local-boundary risks are recorded in [`docs/product-boundaries.md`](docs/product-boundaries.md).

```bash
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](#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 <id>` | See what's waiting for a decision, and exactly what applying it would do |
| `tg-ai plan apply <id>` | Carry out exactly what a saved plan describes |
| `tg-ai plan reject <id>` | Decline a pending plan |
| `tg-ai daemon serve --account <label>` | 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 <id>` |
| MCP client with no shell access (Claude Desktop, most IDE/editor integrations) | immediate | `telegram_plan_<operation>` 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_<operation>` tool — **only under `profile: plan`** | can run `tg-ai plan apply <id>` itself, through its own shell — see the note below |

**Read-only by