telegram-mcp

Claude に、ある Telegram グループから最新の画像を渡します。

スクリーンショットはボットによって投稿され、Telegram Bot API はボット自身のメッセージを返すことはありません。そのため、これは ユーザー アカウントで MTProto（Telethon）を介してグループを読み取ります。それがこれらの写真を見る唯一の方法です。

セットアップ（一度だけ）

1. https://my.telegram.org → API development tools から API ID とハッシュを取得します。

2. cp .env.example .env を実行し、TELEGRAM_API_ID、TELEGRAM_API_HASH、TELEGRAM_CHAT_ID（グループの数値 ID、負の値）を入力します。

3. 環境を作成します:

python -m venv .venv
.venv\Scripts\pip install -e .[dev]

4. サインイン — ターミナルで、Claude 経由ではなく:

.venv\Scripts\telegram-mcp-login

電話番号、Telegram が送信するコード、そして二段階認証パスワード（設定している場合）を尋ね、session/telegram.session を書き込みます。

また、ダイアログを一度リストし、グループの名前を表示します。このリストによって、セッションが後でスーパーグループを解決できるようになります（Telegram はボットが参加するとすぐにグループをスーパーグループに変えます）。そして、その名前が TELEGRAM_CHAT_ID が意図した場所を指していることの確認になります。グループが見つからない場合は、その旨を表示して非ゼロの終了コードで終了します。

Related MCP server: telegram-user-mcp

Claude へのインストール

claude mcp add --scope user telegram -- <abs path>\.venv\Scripts\python -m telegram_mcp.server

ユーザースコープなので、すべてのプロジェクトで利用できます。

ツール

• get_latest_image() — グループ内の最新の写真（過去 200 メッセージを遡る）。

• wait_for_next_image(timeout_seconds=120) — 呼び出し時点より新しい写真が届くまでブロックします。待機中はトークンを消費しません。プロセスはソケット上でアイドル状態になります。MCP クライアントのツールタイムアウト内に収まるよう、1〜240 秒にクランプされます。

どちらも画像（JPEG、長辺 ≤1568 px）とテキスト行を返します。最初に未加工のオリジナルへのパス、次にメッセージ ID、タイムスタンプ、送信者、キャプション（引用符付き）です。縮小で細かい文字が失われる場合は、そのオリジナルを切り取ってください。

同時にセッションを保持できるプロセスは 1 つだけです。最初のセッションが呼び出し中に別の Claude Code セッションがツールを呼び出すと、SQLite エラーを渡される代わりに、少し待って再試行するよう指示されます。

テスト

.venv\Scripts\python -m pytest

ネットワークも Telegram アカウントも不要です。Telethon は全体にわたってフェイクされます。

セキュリティ

session/telegram.session は、あなたの Telegram アカウントへの完全なログインです。これは gitignore されており、このマシンから出ることはありません。そのファイルを保持している人は誰でもあなたのメッセージを読むことができます。コピーされた疑いがある場合は、削除してログインを再実行してください。認証情報は .env にのみ存在します。ドキュメント、プロンプト、チケットには決して含めません。