Better-TG-CLI (Telegram)

https://github.com/user-attachments/assets/d143f7c7-7d50-439c-b373-cbcbff5a6675

Telegram 向けの非公式でエージェントに適したコマンドラインクライアントです。ご自身のアカウント で動作します（teleproto を介した MTProto、TL レイヤー 229）。コマンドは telegram です。読み取り、検索、投稿、ボット、グループ、エクスポート用の約 60 個のコマンドを備え、 AI エージェント（Claude Code、Codex など）が低コストかつ安全に操作できるように構築されています。

$ 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 Seattle @rust_sea | 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?"}]}

警告

**ご自身のアカウントはご自身の責任でご利用ください。**これは、ご本人としてログインする非公式クライアントです。ボットのような動作をするアカウントは、Telegram に制限または凍結される可能性があります。新しいアカウント、一斉メッセージ送信、大量のグループ参加や招待、スパムと見なされる行為は、特にリスクが高くなります。ご自身で Telegram を使うときと同じように利用し、必要でない限り書き込みを無効にしてください。また、エージェントに書き込みを許可する前にSECURITY.mdをお読みください。制限されたアカウントについて、作者は責任を負いません。

目次： このフォークの理由 · インストール · ログイン · 使い方 · MCP サーバー · よくある質問 · 開発 · プライバシー · ライセンス

このフォークについて

エージェント向けに再構成した、skillhq/telegram のフォークです。

• 最新の Telegram レイヤー。 レイヤー 228 以降のリッチなコンテンツを含むボットの返信で、(no text) ではなく実際のテキストが表示されます。ボットのボタンを押して（click）、ボットのメニューを操作できます。
• トークン効率の高い出力。 TTY 以外では、項目ごとに ID を先頭にした簡潔な 1 行が出力され、JSON も空のフィールドを省いて 1 行で出力されます。--max-text で長い投稿を短縮できます。telegram help-all -g <word> を実行すると、コードから生成されたすべてのフラグが表示されます。
• 正確な読み取り。 --since/--until の実際のページネーション、--unread、スレッドとチャンネルのコメント、フォーラムのトピック、ID による get、種類・送信者・日付による検索フィルター、保存したメッセージの me / Избранное に対応しています。
• デフォルトで安全。 人間が write-access on [--for 1h] を実行し、ターミナルのプロンプトまたは macOS のダイアログで確認するまで、アカウントは読み取り専用です。そのため、エージェントが自分で書き込みを有効にすることはできません。すべての書き込みは ~/.config/tg/audit.jsonl に記録されます。シークレットは macOS Keychain、Linux Secret Service、または 1Password に保存されます。
• 小さく、自己完結型。 npm パッケージは 0.3 MB の単一ファイルで、実行時依存関係はありません。Homebrew では Node を必要としないスタンドアロンバイナリがインストールされます。

インストール

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

Windows では（実験的）、Scoop または npm を使用します。

scoop bucket add thevilfer https://github.com/TheVilfer/scoop-bucket
scoop install better-tg-cli

Windows 版の telegram.exe はコード署名されていないため、リリースのダウンロード時に SmartScreen の警告が表示されることがあります。

telegram update は、どの方法でインストールした場合でも、既存のインストールをアップグレードします。ターミナルでは、CLI が 1 日に 1 回、新しいバージョンを確認します。エージェントやパイプにはこの通知は表示されません。また、TG_NO_UPDATE_CHECK=1 で無効にできます。

macOS で Releases からバイナリを手動でダウンロードする場合、Notarization がされていないため、次のコマンドを 1 回実行して隔離フラグを解除してください：xattr -d com.apple.quarantine ./telegram。Homebrew では自動的に処理されます。

@skillhq/telegram はインストールしないでください。GramJS（レイヤー 198）を使用した古い上流ビルドです。

すべての配布チャネルで、1 つのリリースから同じバージョンが提供されます。

配布先	内容	インストール
Homebrew	スタンドアロンバイナリ	brew install thevilfer/tap/better-tg-cli
npm	CLI と MCP サーバー（Node 20 以降）	npm install -g better-tg-cli
Scoop（Windows、実験的）	スタンドアロンの telegram.exe	scoop bucket add thevilfer https://github.com/TheVilfer/scoop-bucket を実行してから、scoop install better-tg-cli
GitHub Releases	バイナリと SHA256SUMS	手動でダウンロード
Claude Code プラグイン	スキルと MCP サーバー	以下を参照
Claude Desktop 拡張機能	Claude 内蔵の Node で動作する MCP サーバー	.mcpb をダウンロードして開く
Grok Build プラグイン	スキルと MCP サーバー	以下を参照
Gemini CLI 拡張機能	スキルと MCP サーバー	gemini extensions install https://github.com/TheVilfer/better-tg-cli
Cursor、VS Code	MCP サーバー	ワンクリックボタン
Grok Bot	Mac から HTTP 経由で接続する MCP サーバー	以下を参照
CLI 自体	Claude Code、Codex、Cursor、Gemini CLI、その他 7 つに対応するエージェントスキル	telegram skill install
skills.sh	あらゆるシェルエージェント向けのエージェントスキル	npx skills add TheVilfer/better-tg-cli
MCP Registry	MCP サーバーエントリー io.github.TheVilfer/better-tg-cli	MCP クライアント経由

Claude Code プラグイン

スキルと MCP サーバーをまとめてインストールできます。

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

MCP サーバーは npx 経由で実行されるため、Node 20 以降で十分です。ターミナルで telegram auth --qr（または npx better-tg-cli auth --qr）を実行して、一度ログインしてください。

Codex プラグイン

同じスキルと MCP サーバーを Codex プラグインとして利用できます（ChatGPT デスクトップアプリにも表示されます）。

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

Grok Build プラグイン

Grok Build は、同じプラグイン、スキル、MCP サーバーをまとめてインストールします。

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

エージェントスキルとして

このスキル（skills/better-tg-cli）は、シェルを使える任意のエージェント（Claude Code、Codex、Cursor、Gemini CLI、OpenCode など）に、CLI を安全に使う方法を教えます。セットアップを確認し、独自にログインすることはなく、書き込み操作は承認を得てから行い、アカウント停止につながりやすい操作パターンを避けます。CLI はスキルを同梱し、自らインストールするため、常にお使いのバージョンと一致します。

telegram skill install                  # every supported agent found on this machine
telegram skill install -a claude-code codex
telegram skill status                   # installed, outdated, linked or missing, per agent

Claude Code、Codex、Cursor、Gemini CLI、GitHub Copilot、Grok Build、OpenCode、Goose、Droid、Windsurf、Pi に対応しています（フォルダーの一覧は telegram skill status で確認できます）。スキルを更新するには、telegram update の後にもう一度実行してください。シンボリックリンクのスキルフォルダーは、--force を指定しない限り変更されません。その他のエージェントでは、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

ログイン

エージェント経由（最も簡単）：Telegram をセットアップするようエージェントに頼むか、自分で telegram onboard を実行してください。127.0.0.1 上にページが開き、better-tg-cli.com でログインキーを取得する（ページに自動で戻ります）か、自分のキーを入力し、QR コードをスキャンして 2FA パスワードを入力できます。エージェントはコマンドを開始して待機するだけです。ログインキー、QR コード、パスワードを目にすることはありません。ページはランダムな秘密のパスでのみ応答し、完了すると閉じます。

自分の API キーを使用する場合（デフォルト）：

1. https://my.telegram.org/apps を開いてアプリケーションを作成し、api_id と api_hash をコピーします。
2. telegram auth --qr を実行し、キーを入力します。次に、スマートフォンで「設定」→「デバイス」→「デスクトップデバイスをリンク」を開き、QR コードをスキャンします。2FA パスワードを設定している場合は入力します。通常の telegram auth では、代わりに電話番号とログインコードを求められます。明るいターミナルテーマで QR コードをスキャンできない場合は、TG_QR_INVERT=1 を指定して実行してください。

ログインキーを使用する場合。 ログインキーを使えば、自分のキーは必要ありません。better-tg-cli.com（コードでメールアドレスを確認します。ページにはインストールガイドもあります）またはメンテナーから取得してください。 telegram auth --login-key --qr を実行してキーを貼り付けるか、TG_LOGIN_KEY=… または --login-key - として渡します。ログインサービス（broker/）は、このログインに限り、アプリのキーを一度だけ提供します。api_hash はお使いのマシンに保存されません。ログインキーは個人用で、最大 3 台のコンピューターで使用でき、取り消すこともできます。0.37 より前はキーを招待と呼んでいました。--invite と TG_INVITE も引き続き使用できます。

セッションは macOS キーチェーン（サービス tg-cli）に保存されます。または、--op-vault <vault> を指定して 1Password に保存できます。telegram logout を実行すると削除されます。Linux では、secret-tool を介して Secret Service（GNOME Keyring、KWallet、KeePassXC）に保存されます。この機能には libsecret-tools パッケージが必要です。設定ファイルにすでに保存されているセッションは、自動的に移動されます。利用できるシークレットストアがない場合、セッションは ~/.config/tg/config.json5（モード 0600）に保存され、書き込みコマンドは無効のままになります。 Linux では、write-access on はターミナルのプロンプトで確認します。Windows では、シークレットは %APPDATA%\tg\secrets.dpapi に保存され、Windows ユーザー向けに DPAPI で暗号化されます（このマシンで復号できるのは本人だけです）。ターミナルがない場合、write-access on は「はい／いいえ」のウィンドウで確認を求めます。

使用方法

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 drafts                               # saved but unsent drafts
telegram admin-log "Team"                     # a group's recent admin actions
telegram profile-photos @alice                # a user's profile photos
telegram read @channel -n 20 --full           # every message stat (views, reactions, flags, media)
telegram stats "Mock News" --graphs           # full channel stats + growth graphs; --message <id> / --story <id> too
telegram sessions ; telegram stars            # active login sessions; Telegram Stars balance & transactions
telegram invites "Team" --requests            # a chat's invite links, or its pending join requests

telegram write-access on --for 1h             # a human confirms this
telegram send @alice "on my way"
printf '%s' "$text" | telegram send @alice -  # long or multi-line text: from stdin, no quoting problems
telegram reply "Chat" 812 "on it" --silent
telegram click @SomeBot 4410 "Settings"       # press an inline button
telegram pin-chat @alice                      # pin a chat; mark-unread / delete-dialog too
telegram edit-permissions "Team" @alice --mute --until 1d   # restrict a member; --lift to undo
telegram topic create "Dev Forum" "Release 2.0"            # forum topics: create/edit/close/reopen/pin

telegram api messages.GetAllDrafts            # call any raw TL method (full API reachability)
telegram api channels.GetAdminLog --params '{"channel":{"_chat":"Team"},"limit":20,"q":""}'
telegram messages get-history --peer @durov --limit 10      # or a typed command per TL method
telegram account get-authorizations           # telegram <namespace> --help lists a namespace
telegram help get-config                      # telegram ping, telegram req-pq, … for root methods

読み取りコマンドでは --json を指定できます。また、一部のコマンドでは --markdown も指定できます。read／get／search／inbox／watch では --full（別名 --stats）を指定すると、メッセージごとのすべての統計情報（閲覧数、転送数、リアクションの詳細、コメント、フラグ、リッチメディアのメタデータ）が含まれます。このオプションを指定しない場合、デフォルトの出力は変わりません。 すべてのコマンドは telegram help-all で確認できます。reference.md では、フラグ一覧だけでは説明しきれない動作（出力形式、スレッド、ボタン付きボット、管理者コマンド、トラブルシューティング）を説明しています。汎用コマンド telegram api <namespace.Method> から Telegram クライアント API の全機能（100%）にアクセスできるほか、823 個すべての TL メソッドには、スキーマから生成された型付きトップレベルコマンド telegram <namespace> <method>（telegram ping などのルートメソッドも含む）があり、api と同じ拒否ルールと読み取り／書き込みガードが適用されます。名前空間名が厳選コマンド（stats、stories、contacts、auth、folders、help）と重複する場合、厳選コマンドはそのまま維持され、生成されたメソッドはサブコマンドとして追加されます。サブコマンドが選択されるのは、最初の語がメソッド名と完全に一致する場合のみです（メソッド名と同じ名前のチャットを指定するには、名前を引用符で囲むか ID を使用してください）。各メソッドには、公式の説明とパラメーターごとのドキュメント（core.telegram.org から取得）が付属しています。telegram <namespace> --help では、名前空間内のメソッドが [read]／[write]／[refused] のマーク付きで一覧表示されます。telegram <namespace> <method> --help では、パラメーター、例、ドキュメントへのリンクが表示されます。telegram schema [<ns> [<method>]] では、同じ内容が JSON で出力されます。 docs/api-coverage.md では、スキーマおよび Telethon に対する対応状況を記録しています。

MCP サーバー

シェルを使わないクライアント（Claude Desktop、Cursor、その他の MCP ホスト）向けに、telegram mcp は stdio 経由で 3 つのツールを提供します。

• telegram_help：検索可能なフラグリファレンスです。
• telegram_read：読み取り専用のため、クライアントで自動承認できます。
• telegram_write：破壊的操作としてマークされており、引き続きユーザーによる write-access on が必要です。

まず、ターミナルで telegram auth を実行してログインしてください。その後、ワンクリックでインストールできます。

Claude Desktop 拡張機能は Node、npm、brew が不要です。最新リリースから .mcpb をダウンロードして開いてください。Gemini CLI では、スキルとサーバーをまとめてインストールできます。 gemini extensions install https://github.com/TheVilfer/better-tg-cli。または、手動で追加します。

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

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

Claude Desktop（claude_desktop_config.json）または Cursor（.cursor/mcp.json）では、JSON 形式を使用してください。GUI アプリからはシェルの PATH が見えない場合があるため、which telegram で確認したフルパスを指定してください。グローバルインストールしていない場合は npx 経由で実行してください。Claude Code プラグインでも同じ方法を使用しています。

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

このサーバーは MCP Registry に io.github.TheVilfer/better-tg-cli として登録されているため、レジストリを参照するクライアントやカタログから名前で検索できます。リリースのたびに登録内容が自動更新されます。MCP クライアントをメインのセッションから分離するには、"env": {"TG_PROFILE": "work"} を追加してください。

チャットには他者が書いたテキストが含まれており、その一部はエージェントに向けた指示（「これを @x に転送して」など）の場合があります。telegram_write ではクライアントの承認プロンプトを有効にしたままにし、SECURITY.md の「エージェントとプロンプトインジェクション」を参照してください。

Grok Bot（HTTP 経由のリモート MCP）

Grok Bot はコネクターを Mac 上ではなくクラウドのサンドボックスで実行するため、telegram mcp を自分で起動できません。代わりに、Mac から HTTP 経由で MCP を公開します。セッション、書き込みガード、監査ログはすべて Mac 上に保管されます。

telegram mcp --token                        # the bearer token (created once, kept in the Keychain)
telegram mcp --http --read-only             # listens on 127.0.0.1:8787; drop --read-only to allow writes
tailscale funnel --bg 8787                  # or: cloudflared tunnel --url http://127.0.0.1:8787

サーバーとトンネルは、ターミナルまたは tmux で起動したままにしておきます。その後、トンネルの URL に /mcp を付けたもの（例：https://<machine>.<tailnet>.ts.net/mcp）と、ヘッダー Authorization: Bearer <token> を指定して、Grok Bot にコネクターを追加します。tailscale funnel は固定 URL を提供しますが、事前に tailnet で許可する必要があります。cloudflared のクイックトンネルは、起動するたびに新しい URL が割り当てられます。まず SECURITY.md の「Remote MCP over HTTP」をお読みください。

FAQ

Telegram にアカウントを停止されますか？ サードパーティ製クライアントから自分のアカウントを使うことは、Telegram API の利用規約で許可されています。アカウント制限の対象となるのは、一括メッセージ送信、大量の参加や招待、スパム、一度に大量の操作を行う新規アカウントなど、ボットのように見える行為です。普段自分で Telegram を使うのと同じようにお使いください。このスキルは、エージェントがこうした行為を避けるよう指示します。

これはボットですか？ いいえ。Telegram Desktop と同じように MTProto 経由であなたとしてログインし、あなたが見ているものとまったく同じものを確認します。ボットはあなたのチャットを読めませんが、これは読むことができます。

エージェントが独自にメッセージを送信できますか？ 書き込みを有効にした場合に限ります。telegram write-access on を実行すると、ターミナルまたは macOS のダイアログで確認を求められますが、エージェントはこれに応答できません。その後の書き込みには、正確なチャットの指定が必要で、各操作が記録されます。MCP 経由での書き込みは別のツールとして提供され、クライアントから毎回承認を求めることができます。詳しくは SECURITY.md をご覧ください。

メッセージを読むと既読になりますか？ いいえ。read、inbox、search を実行してもチャットは未読のままです。既読にするのは telegram mark-read だけです。

自分の API キーが必要ですか？ はい。my.telegram.org/apps から取得してください。無料で、作成には 1 分ほどしかかかりません。better-tg-cli.com のログインキーを使えば、telegram auth --login-key --qr で API キーなしでログインできます。

セッションはどこに保存され、誰がメッセージを見られますか？ セッションは macOS Keychain、Linux Secret Service、または 1Password に保存されます。CLI は Telegram と直接通信し、分析データは収集しません。ほかに通信するホストは、毎日のバージョン確認で使う npm と、ログインキーでログインする際のログインサービスだけです。PRIVACY.md をご覧ください。

複数のアカウントを使えますか？ はい。TG_PROFILE を使うと、それぞれのプロファイルに個別のログイン情報、設定、Keychain の項目が用意されます。例：TG_PROFILE=work telegram auth --qr。アカウントの切り替え機能は #5 で追跡しています。

Windows で動作しますか？ はい。実験的な対応です。scoop install better-tg-cli または npm でインストールできます。シークレットは Windows DPAPI で保存され、CI では Windows 上でテストが実行されますが、実際の利用については macOS や Linux ほど十分にテストされていません。問題があれば、issue でお知らせください。

Grok Bot、ChatGPT、その他のクラウドエージェントから利用できますか？ クラウドエージェントは、あなたのコンピューター上でプログラムを起動できません。そのため、MCP サーバーを HTTP 経由で実行し、トンネル経由で接続してください。Grok Bot をご覧ください。

アップデートするにはどうすればよいですか？ telegram update を実行してください。インストール元と同じ配布経路（Homebrew、npm、リリースバイナリ）が使用されます。telegram skill install でエージェントスキルをインストールした場合は、再度実行すると更新できます。

開発

DEVELOPMENT.md では、以下について説明しています。

• ソースからの実行（scripts/tg-dev）；
• 実際のセッションには一切触れない、分離された開発用プロファイル（TG_PROFILE）；
• Telegram テストサーバー；
• エディターでのデバッグとテスト。

リリースは scripts/release.sh で作成します（リリース PR を作成し、バージョンは PR のタイトルから決まります）。マージ後に scripts/release.sh tag を実行します。タグを作成するとバイナリがビルドされ、GitHub Releases、npm（provenance 付きの信頼された公開）、Homebrew tap、MCP Registry に公開されます。CONTRIBUTING.md をご覧ください。

アンインストール

1. telegram logout を実行すると、保存されたセッションが削除されます。Telegram 側でもセッションを終了するには、Telegram → 設定 → デバイスで終了してください。
2. telegram skill uninstall を実行すると、インストール先のエージェントからスキルが削除されます。
3. プログラムを削除します：brew uninstall better-tg-cli、npm uninstall -g better-tg-cli、または scoop uninstall better-tg-cli を実行してください。Releases から入手したバイナリの場合は、telegram / telegram.exe を削除してください。
4. 設定フォルダー ~/.config/tg（Windows では %APPDATA%\tg）と、使用した TG_PROFILE ごとの ~/.config/tg-<profile> を削除してください。Windows では、これにより DPAPI シークレットファイルも削除されます。それ以外の環境では、api_hash と書き込みアクセスフラグはシークレットストアに残ります。Keychain Access の tg-cli 項目（または secret-tool clear service tg-cli）を削除するか、1Password の保管庫にある項目を削除してください。

プライバシー

アナリティクスはありません。当社が運用するサービスは任意のログインサービスのみで、メッセージやセッションを参照することはありません。CLI が通信する 3 つのホストと、ローカルに保存する情報については PRIVACY.md をご覧ください。

コード署名ポリシー

Windows バイナリは、個人のマシンではなく、このリポジトリから GitHub Actions のみを使ってビルドしています（.github/workflows/release.yml）。SignPath Foundation による無料のコード署名を申請済みです。導入後、リリースバイナリには次の表示が付きます：無料のコード署名は SignPath.io が提供し、証明書は SignPath Foundation が提供します。 それまでは、Windows の telegram.exe は署名されておらず、macOS バイナリはアドホック署名されています。

• コミッターおよびレビュー担当者：@TheVilfer
• 承認者（署名済みの各リリース）：@TheVilfer
• プライバシーポリシー：PRIVACY.md。CLI が通信するのは、Telegram、ログインキーを使ってログインする際のログインサービス、およびターミナルでの毎日の更新確認に使用する npm レジストリのみです（TG_NO_UPDATE_CHECK=1 で無効化できます）。

ライセンス

MIT です。LICENSE をご覧ください。Derek Rein による skillhq/telegram を基にしています。Telegram とは提携しておらず、Telegram による推奨も受けていません。「Telegram」は所有者の商標です。Telegram API 利用規約に従って使用してください。