Telegram AI CLI MCP server

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

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

Shortened. The full README is on GitHub.