CLI and MCP server for AI agents on a personal Telegram account

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 <id> 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 <id> (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 <id> 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 that class of client, this design does not pretend to hold a hard line at plan/apply. The line it actually offers is: every attempt and every outcome is written to the audit log before and after the RPC (audit.py), rate limits persist across restarts so an agent (or an injection driving one) cannot out-run them by being restarted (limits.py), the hard denylist on 777000 (Telegram's login-code chat) and Saved Messages cannot be reconfigured away, and everything an agent is about to approve is sanitized before it reaches a terminal so the text being approved is the text that will actually send (render.py). If your MCP client can run shell commands, you are trusting the agent, and the safety net is visibility and limits, not an unbreakable gate. A profile named full — direct send with no plan step, from any caller — does not exist in this project; it was considered and rejected. A stronger boundary (a separate OS principal, or a TOTP-gated apply) is out of scope for v0.1 and is written up as a path forward in docs/threat-model.md.

Reading, chats and profiles

Groups and channels are readable as soon as an account is configured; direct messages are not readable until a chat id is explicitly allowlisted — an empty dms allowlist means none, not all. 777000 (Telegram Service Notifications, where login codes and 2FA resets arrive) and Saved Messages are closed in code and cannot be reopened by any configuration. Every write capability (send, admin, join, profile changes) is fail-closed the same way: an empty list means nothing is permitted until you add to it. Two profiles exist — readonly (default: only the read and local tools are published) and plan (read, plus creating plans; the plan tools appear only under it). See telegram_ai_cli_mcp/safety.py for the exact rule order.

Importing an existing session

Importing a tdata folder from Telegram Desktop is one way to authorize an account without a fresh login flow. Two things to know before you do it:

• USE_CURRENT_SESSION logs the original Telegram Desktop out. Converting tdata into a usable MTProto session can either mint a brand-new session (the desktop app stays logged in) or take over the existing one (the desktop app is signed out the moment the imported session connects). If you want to keep using Telegram Desktop with the account you're importing, do not ask for the current-session mode.
• Telegram treats a .session file as equivalent to holding the account's auth key. Anyone who obtains it controls the account until the session is revoked from a device. Store it accordingly — see docs/threat-model.md.

Install

uvx --from telegram-ai-cli-mcp tg-ai mcp

That one command is the server. It speaks MCP on stdin and waits; every client block below runs the same uvx command. Sign the account in first, from a terminal, because neither the server nor the Desktop extension can prompt for a login code:

uvx --from telegram-ai-cli-mcp tg-ai account login --label work --phone "<your phone, E.164>"

--label names the account; put your own number in E.164 form; --phone is needed only on the first sign-in of that label. account login-qr --label work signs in by QR code instead, with no phone number.

The session is stored under ~/.local/state/telegram-ai-cli-mcp/. The server sends nothing by itself: a plan tool records an intention, and a person applies it with tg-ai plan apply.

The package is telegram-ai-cli-mcp on PyPI; uvx caches what it installed and may keep running that version; --from telegram-ai-cli-mcp@latest checks PyPI again, and --from telegram-ai-cli-mcp==0.1.3 pins one. This README follows main, so what the changelog lists under Unreleased is not in the PyPI release yet. Since 0.1.2 the readonly profile lists no telegram_plan_* tool; 0.1.1 and earlier still list them under readonly and refuse every call, so a uvx cache holding one of those shows plan tools that do not work. To run main itself, use uvx --from git+https://github.com/stufently/telegram-ai-cli-mcp tg-ai mcp. For a lasting tg-ai on PATH, pipx install telegram-ai-cli-mcp or uv tool install telegram-ai-cli-mcp. A checkout still works, for development:

git clone https://github.com/stufently/telegram-ai-cli-mcp.git
cd telegram-ai-cli-mcp
pip install .
tg-ai --version

Give it an environment of its own — pipx, uv tool, or a plain python3 -m venv — rather than a shared user site, and put the resulting bin/tg-ai on PATH. The dependency floor here is deliberately current (mcp>=2.0, telethon>=1.44), and a shared site-packages holds exactly one version of a package for every program on the machine: anything pinned below that floor loses, silently, the moment this project is installed or upgraded alongside it.

That collision is live on the maintainer's host, where the tg-claude-userbot project pins mcp==1.27.2 and telethon==1.43.2. Since 2026-09-03 tg-ai lives in its own virtualenv there and the shared entry point is a symlink into it:

/home/deploy/.venvs/tg-ai            # editable install of this repo
/home/deploy/.local/bin/tg-ai   ->   /home/deploy/.venvs/tg-ai/bin/tg-ai

Details of that layout, and what was left behind in the shared site, are in Operations.

docker build -t telegram-ai-cli-mcp .
docker run --rm telegram-ai-cli-mcp --version   # arguments go to tg-ai
docker run --rm -i telegram-ai-cli-mcp          # default: tg-ai mcp over stdio

Example prompts

Ask in plain language. The server picks the tool.

• What did I miss in Telegram since yesterday morning?
• Who mentioned me in the project chat, and what did they actually say?
• Who is this username, and which groups do we have in common?
• Draft a reply to Alex's last message, but do not send it.
• Which devices is this account signed in on right now?