# telegram-ai-cli-mcp > Read chats, search messages and resolve usernames over MTProto from Claude Code, Claude Desktop, Codex or Cursor; every write is a plan a person applies. Source code: https://github.com/stufently/telegram-ai-cli-mcp License: MIT - Task-shaped access to a personal Telegram account over MTProto: read chats, search messages, resolve who a username belongs to, check who is in a group. - Plan, then apply: anything that changes something on Telegram is saved as a plan, and only tg-ai plan apply carries it out. No MCP tool applies a plan. - Read-only by default: the readonly profile publishes no telegram_plan_* tools; plan tools appear only under profile: plan. - Fail-closed allowlists: direct messages, sending, joining and admin actions are closed until chat ids are listed; 777000 and Saved Messages are closed in code. - Audit log before and after every RPC, rate limits that persist across restarts, and an identical-send ledger. - One CLI with a --json form and an MCP server over stdio or loopback HTTP with a bearer token; installs with uvx, pipx, uv tool or Docker. ## Documentation - [telegram-ai-cli-mcp — CLI and MCP server for AI agents on a personal Telegram account](https://stufently.github.io/telegram-ai-cli-mcp/docs/): 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… - [Operations reference](https://stufently.github.io/telegram-ai-cli-mcp/docs/operations/): Every capability of this tool is declared once, as an Operation in opspec.py. The CLI renders that declaration into a command, the MCP server renders it… - [Configuration reference](https://stufently.github.io/telegram-ai-cli-mcp/docs/configuration/): Everything on this page is defined in config.py and read exactly once per process into a Settings object. Policy decisions are made against that object,… - [Threat model](https://stufently.github.io/telegram-ai-cli-mcp/docs/threat-model/): This is the fuller version of the reasoning summarized in SECURITY.md. It exists so a reader deciding whether to trust this tool with their own Telegram… - [Product boundaries for v0.1](https://stufently.github.io/telegram-ai-cli-mcp/docs/product-boundaries/): This file turns “maybe someday” notes into explicit decisions. The project is a bounded personal-account CLI/MCP server, not a general Telegram client, a… ### How do I let Claude read my Telegram? Run tg-ai mcp and register it as an MCP server with Claude Code or Claude Desktop. The readonly profile is active by default and groups and channels are readable immediately; direct messages stay closed until you add specific chat ids to safety.read.dms.allow. ### Is there an MCP server for Telegram user accounts? Yes, this one. It is built on MTProto through Telethon, not the Bot API, so it can read existing chat history, resolve usernames and see who is in a group the way a human member's client can. ### Can an AI agent send messages on my Telegram account through this? Only after a two-step plan and apply. An MCP client without shell access cannot apply a plan. A client that also has a shell (Claude Code, Codex and similar) can run tg-ai plan apply itself, so for those the safety net is the audit log and rate limits, not a hard gate. ### Is this a Telegram bot? No. It automates a personal user account over MTProto. A Bot API bot is a different kind of Telegram entity with different limits and different visibility into chat history. ### Will Telegram ban my account for using this? Telegram can limit or ban any account it judges to be running abusive automation, whatever tool sent the requests. The tool is built around ordinary reading and occasional allowlisted sending; mass joins, high-volume sends and member scraping are not something it tries to make safe. ### Which Python version do I need? 3.12 or newer; 3.12 to 3.14 are tested in CI. Linux is tested, macOS is expected to work but not tested, and Windows is not supported because session locking uses fcntl. ## Optional - [Full text of all docs](https://stufently.github.io/telegram-ai-cli-mcp/llms-full.txt)