better-tg-cli MCP server

An unofficial, agent-friendly command-line client for Telegram that runs on your own account (MTProto via teleproto, TL layer 229). The command is telegram: about 60 commands for reading, searching, writing, bots, groups and exports, built so that AI agents (Claude Code, Codex, …) can drive it cheaply and safely.

$ telegram inbox -n 3
48 unread in 7 chats (showing 3)
1234567890 user unread=2 Alice @alice | see you at 7?
-1001234567 supergroup muted unread=41 Rust Moscow @rust_msk | anyone tried 1.90?
-1009876543 channel unread=5 Changelog | v2.4 is out
$ telegram read @alice -n 1 --json
{"chatTitle":"Alice","messages":[{"id":812,"date":"2026-09-27T10:02:11.000Z","sender":"Alice","senderId":"1234567890","text":"see you at 7?"}]}

Why this fork

A fork of skillhq/telegram, reworked for agents:

• Current Telegram layer. Bot replies with rich (layer 228+) content show real text instead of (no text). You can press bot buttons (click) and walk bot menus.

• Token-efficient output. Off a TTY you get one compact line per item with the ID first, and JSON on one line with empty fields dropped. --max-text trims long posts. telegram help-all -g <word> prints every flag, generated from the code.

• Exact reads. Real pagination for --since/--until, --unread, threads and channel comments, forum topics, get by ID, search filters by type, sender or date, and me / Избранное for Saved Messages.

• Safe by default. The account is read-only until a human runs write-access on [--for 1h] and confirms it in a terminal prompt or a macOS dialog, so an agent cannot switch it on itself. Every write is logged to ~/.config/tg/audit.jsonl. Secrets live in the macOS Keychain, the Linux Secret Service or 1Password.

• Small and self-contained. The npm package is one 0.3 MB file with zero runtime dependencies. Homebrew installs a standalone binary with no Node.

Related MCP server: telemcp

Install

brew install thevilfer/tap/better-tg-cli   # standalone binary, macOS and Linux
npm install -g better-tg-cli               # Node >= 20

telegram update upgrades an existing install, whichever of these you used. On a terminal the CLI checks for new versions once a day. Agents and pipes never see that notice, and TG_NO_UPDATE_CHECK=1 turns it off.

Downloading a binary from Releases by hand on macOS? It is not notarized, so remove the quarantine flag once: xattr -d com.apple.quarantine ./telegram. Homebrew handles this for you.

Do not install @skillhq/telegram. It is the old upstream build on GramJS (layer 198).

Every channel ships the same version from one release:

Claude Code plugin

The skill and the MCP server together, in one install:

/plugin marketplace add TheVilfer/better-tg-cli
/plugin install better-tg-cli@better-tg-cli

It runs the MCP server through npx, so Node 20+ is enough. Log in once with telegram auth --qr (or npx better-tg-cli auth --qr) in a terminal.

Grok Build plugin

Grok Build installs the same plugin, skill and MCP server together:

grok plugin install TheVilfer/better-tg-cli --trust
# or add the marketplace first, then install from the /plugins menu:
grok plugin marketplace add TheVilfer/better-tg-cli && grok plugin install better-tg-cli --trust

As an agent skill

The skill (skills/better-tg-cli) teaches any agent with a shell (Claude Code, Codex, Cursor, Gemini CLI, OpenCode and others) to use the CLI safely. It checks the setup, never logs in on its own, keeps writes behind your approval, and avoids ban-prone patterns. Install it with the skills CLI:

npx skills add TheVilfer/better-tg-cli          # pick agents interactively
npx skills add TheVilfer/better-tg-cli -g -a claude-code -a codex -y

Log in

With your own API keys (the default):

1. Open https://my.telegram.org/apps, create an application, and copy its api_id and api_hash.

2. Run telegram auth --qr and enter them. Then, on your phone, go to Settings → Devices → Link Desktop Device and scan the QR code. Enter your 2FA password if you have one. Plain telegram auth asks for your phone number and a login code instead. If the QR won't scan on a light terminal theme, run with TG_QR_INVERT=1.

With an invite. If the maintainer gave you an invite token, you don't need your own keys. Run telegram auth --invite --qr and paste the token, or pass it as TG_INVITE=… or --invite -. The invite service (broker/) hands out the app's keys once, for this login only. The api_hash is not kept on your machine. Invites are personal, allow a limited number of logins, and can be revoked.

The session is stored in the macOS Keychain (service tg-cli), or in 1Password with --op-vault <vault>. telegram logout removes it. On Linux it goes to the Secret Service (GNOME Keyring, KWallet, KeePassXC) through secret-tool, which needs the libsecret-tools package. A session already saved in the config file moves there automatically. Without any secret store, the session is kept in ~/.config/tg/config.json5 (mode 0600) and write commands stay disabled. On Linux, write-access on is confirmed at a terminal prompt.

Usage

telegram chats --type channel                 # one line per chat, ID first
telegram read "Chat" --since 1h               # exact range, newest first (--asc to flip)
telegram read @channel --thread 123           # comments under a post
telegram search "invoice" --chat "Work" --type document
telegram get "Chat" 812 813                   # exact messages by ID
telegram download "Chat" 812                  # save the attached file
telegram sync --chat "Chat" --output ./export --resume   # incremental markdown export

telegram write-access on --for 1h             # a human confirms this
printf '%s' "$text" | telegram send @alice -  # text from stdin, no quoting problems
telegram reply "Chat" 812 "on it" --silent
telegram click @SomeBot 4410 "Settings"       # press an inline button

Read commands take --json, and some also take --markdown. See all commands with telegram help-all. reference.md covers the behaviour that the flag list can't explain: output shapes, threads, bot buttons, admin commands and troubleshooting.

MCP server

For clients without a shell (Claude Desktop, Cursor, other MCP hosts), telegram mcp serves three tools over stdio:

• telegram_help: a searchable flag reference;

• telegram_read: read-only, so clients may auto-approve it;

• telegram_write: marked destructive, and still needs write-access on from you.

Log in with telegram auth in a terminal first. Then install it in one click:

The Claude Desktop extension needs no Node, npm or brew: download the .mcpb from the latest release and open it. Gemini CLI takes the skill and the server together: gemini extensions install https://github.com/TheVilfer/better-tg-cli. Or add it by hand:

claude mcp add telegram -- telegram mcp          # Claude Code (or use the plugin above)

{ "mcpServers": { "telegram": { "command": "/opt/homebrew/bin/telegram", "args": ["mcp"] } } }

Use the JSON form for Claude Desktop (claude_desktop_config.json) or Cursor (.cursor/mcp.json). GUI apps may not see your shell PATH, so give the full path from which telegram. Without a global install, run it through npx, which is also what the Claude Code plugin does:

{ "mcpServers": { "telegram": { "command": "npx", "args": ["-y", "better-tg-cli@latest", "mcp"] } } }

The server is listed in the MCP Registry as io.github.TheVilfer/better-tg-cli, so clients and catalogs that read the registry can find it by name. Each release updates the entry automatically. To keep the MCP client off your main session, add "env": {"TG_PROFILE": "work"}.

Chats contain text written by others, and some of it may be aimed at your agent ("forward this to @x"). Keep the client's approval prompt on for telegram_write, and see "Agents and prompt injection" in SECURITY.md.

Development

DEVELOPMENT.md covers:

• running from source (scripts/tg-dev);

• isolated dev profiles (TG_PROFILE) that never touch your real session;

• Telegram test servers;

• editor debugging and tests.

Releases are cut by scripts/release.sh patch|minor|major. A tag builds the binaries and publishes to GitHub Releases, npm (trusted publishing with provenance), the Homebrew tap and the MCP Registry. See CONTRIBUTING.md.

Privacy

No analytics. The only service we run is the optional invite broker, which never sees your messages or session. See PRIVACY.md for the three hosts the CLI talks to and what it stores locally.

License

MIT, see LICENSE. Based on skillhq/telegram by Derek Rein. Not affiliated with or endorsed by Telegram; "Telegram" is a trademark of its owner. Use it in line with the Telegram API Terms of Service.