Telegram MCP

telegram

mcp-name: io.github.n24q02m/better-telegram-mcp

AI エージェント向け Telegram：ボットモードとユーザーアカウントモードで、メッセージ、チャット、メディア、連絡先を扱えます。

n24q02m の関連プロジェクト（クリックして展開）

| プロジェクト | キャッチコピー | タグ | |---|---|---| | [agent-chat-plugin](https://github.com/n24q02m/agent-chat-plugin) | 共有フォルダー内でAIエージェント同士がチャット — 人間の仲介もオーケストレーターも不要。... | ツール | | [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | トークン効率の高いコードレビューのためのナレッジグラフ — セマンティック検索と呼び出し... | MCP | | [better-drive](https://github.com/n24q02m/better-drive) | .driveignoreフィルターを備えた双方向Google Drive同期 — rcloneエンジン、Windowsトレイ | ツール | | [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | AIエージェント向けIMAP/SMTPメール — メールの読み取り、送信、フォルダーの整理、添付ファイルの管理... | MCP | | [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | Godot Engine向け複合MCPサーバー — AI支援のゲーム開発を実現する17個の複合ツール... | MCP | | [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | AIエージェント向けのMarkdownファーストなNotion — ページ、データベース、ブロック、コメント... | MCP | | [better-semantic-release](https://github.com/n24q02m/better-semantic-release) | リリースの安全性を守るガード機能を組み込んだ、差し替え可能なpython-semantic-releaseのフォーク（... | ツール | | [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | AIエージェント向けTelegram — 両方のボ...にわたるメッセージ、チャット、メディア、連絡先 | MCP | | [better-workspace-mcp](https://github.com/n24q02m/better-workspace-mcp) | Google Workspace MCPサーバー（Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...） | MCP | | [claude-plugins](https://github.com/n24q02m/claude-plugins) | n24q02mのMCPサーバー向けClaude Codeプラグインマーケットプレイス — ウェブ検索をインストール... | マーケットプレイス | | [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | AIエージェント向けの画像・動画の理解と生成 — Gemini、Op...に対応 | MCP | | [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | batchexecute APIを介してJulesタスクを一括操作するChrome拡張機能 — ... | ツール | | [mcp-core](https://github.com/n24q02m/mcp-core) | MCPサーバー構築のための共有基盤 — Streamable HTTPトランスポート、OAuth... | MCP | | [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | ハイブリッド検索と埋め込み同期を備えた永続的なAIメモリ。オープン、無料、無制限... | MCP | | [qwen3-embed](https://github.com/n24q02m/qwen3-embed) | ONNX RuntimeとGGUFを介した軽量なQwen3テキスト埋め込みと再ランキング | ライブラリ | | [skret](https://github.com/n24q02m/skret) | サーバー不要のシークレット管理。 | CLI | | [tacet](https://github.com/n24q02m/tacet) | ナレッジ...全体でLLMコストを償却する、自己蒸留型のニューロシンボリック・カスケード | ツール | | [web-core](https://github.com/n24q02m/web-core) | 検索、スクレイピング、HTTPセキュリティ、st...向けの共有ウェブインフラストラクチャパッケージ | ライブラリ | | [wet-mcp](https://github.com/n24q02m/wet-mcp) | AIエージェント向けのオープンソースMCPサーバー：ウェブ検索、コンテンツ抽出、ライブラリ... | MCP |

目次

• 機能
• インストール
• セットアップ
• Smithery
• 設定
• HTTPモード
• CLI
• ツール
• 比較
• セキュリティ
• ソースからビルド
• 信頼モデル
• ライセンス

## 特長

• デュアルモード -- ボットには Bot API（httpx）、ユーザーアカウントには MTProto（Telethon）を使用します
• 6 つのツールとアクションディスパッチ：message、chat、media、contact、config、help
• モードの自動検出 -- ボットモードではボットトークンを、ユーザーモードでは電話番号を設定します
• ローカル CLI 認証 -- telegram auth で、サーバーを実行するマシン上でボットトークン、または電話番号＋OTP＋2FA を処理します
• stdio または HTTP -- デフォルトは stdio、HTTP は認証なし（ループバックのみ）、単一のベアラートークン、またはユーザーごとのトークンに対応します
• ツールのアノテーション -- 各ツールで readOnlyHint、destructiveHint、idempotentHint、openWorldHint を宣言します
• MCP リソース -- ドキュメントを telegram://docs/* リソースとして利用できます
• セキュリティ強化 -- SSRF 対策、パストラバーサル防止、エラーのサニタイズ、Telegram コンテンツへのプロンプトインジェクション境界タグに対応します

インストール

# Claude Code plugin (stdio, bot mode)
/plugin marketplace add n24q02m/claude-plugins
/plugin install better-telegram-mcp@n24q02m-plugins

# Direct uvx invocation (stdio, bot mode)
claude mcp add telegram -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF -- uvx n24q02m-telegram

# Docker stdio
docker run -i --rm -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF n24q02m/telegram

パッケージ名は n24q02m-telegram です（以前は better-telegram-mcp。旧パッケージは最後のリリースを行った後、更新を停止します）。MCP Registry の ID は引き続き io.github.n24q02m/better-telegram-mcp、Docker イメージは n24q02m/telegram です。また、従来の better-telegram-mcp コマンドは telegram のエイリアスとして残ります。初回起動時に、ローカルデータは ~/.better-telegram-mcp から ~/.telegram に一度だけ移行されます。

インストールマトリックス

クライアント	インストール
Claude Code	/plugin marketplace add n24q02m/claude-plugins + /plugin install better-telegram-mcp@n24q02m-plugins（stdio ボットモード）、または上記のブロックに記載されているように claude mcp add を使用します
Cursor / Windsurf / Gemini CLI / 任意の MCP クライアント	クライアントの設定にある mcpServers JSON で、stdio の command を指定するか、type: "http" と、実行するサーバーを指す url を指定します（HTTP モードを参照）

AI エージェントでインストール -- 次の内容を AI コーディングエージェントに貼り付けます：

https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-telegram-mcp/setup-with-agent.md の手順に従って MCP サーバー telegram をインストールしてください

セットアップ

認証情報は、サーバーを実行するマシン上で設定します。

ボットモード： クライアント設定で TELEGRAM_BOT_TOKEN を設定するか、一度だけ保存します：

telegram auth --bot-token 123456:ABC-DEF

ユーザーモード： 電話番号を使って対話形式でサインインします。Telegram から OTP が送信されます。アカウントに 2FA が設定されている場合は、2FA パスワードの入力を求められます。Telethon セッションはディスクに保存されます。

telegram auth --phone +15551234567

telegram status で結果を確認します。サーバーは起動時に保存済みの認証情報を読み込むため、telegram auth の後に再起動してください。認証情報がない場合、stdio サーバーはこれらの手順を stderr に出力して、ステータス 1 で終了します。

Smithery

Smithery にも掲載されています。smithery.yaml に従い、Smithery は uvx --python 3.13 n24q02m-telegram を使って stdio 経由でサーバーを起動し、インストール時の設定は不要です（configSchema は空です）。認証情報は TELEGRAM_BOT_TOKEN 環境変数、または事前に実行した telegram auth から取得されます（セットアップを参照）。

設定

設定は TELEGRAM_ を接頭辞とする環境変数から読み込まれます（Pydantic Settings）。環境変数は telegram auth で保存した認証情報より優先されます。

変数	必須	説明
TELEGRAM_BOT_TOKEN	ボットモード	@BotFather から取得したボットトークン（形式は 123456789:ABCdef...）
TELEGRAM_PHONE	ユーザーモード	+<country><number> 形式の電話番号
TELEGRAM_API_ID / TELEGRAM_API_HASH	いいえ	同梱の公開 API ペアを上書きします
USE_BUNDLED_TELEGRAM_CLIENT	いいえ	独自の API ペアを必須にするには false に設定します
TELEGRAM_SESSION_NAME	いいえ	Telethon セッションファイル名（デフォルトは default）
TELEGRAM_DATA_DIR	いいえ	セッションディレクトリ（デフォルトは ~/.telegram）
MCP_TRANSPORT	いいえ	HTTP モードで起動するには http に設定します（--http または TRANSPORT_MODE=http も使用できます）

TELEGRAM_PASSWORD 環境変数はありません。telegram auth は 2FA パスワードの入力を求めますが、その値を環境変数に保存することはありません。

HTTP モード

telegram --http は /mcp で MCP を、認証なしの GET /health でヘルスチェックを提供します。 設定は ~/.telegram/config.toml にあります。

[server]
host = "127.0.0.1"   # default; --host overrides
port = 8000          # default; --port overrides
auth = "token"       # "no-auth" | "token" | "multi"
token_hash = "scrypt$..."

auth	接続できるユーザー	使用する認証情報
no-auth	ポートに接続できるすべてのユーザー。ループバックアドレスのみでバインドされます（ループバック以外のホストは拒否されます）	デフォルトの認証情報
token	token_hash に一致する Authorization: Bearer <token> を送信するクライアント	デフォルトの認証情報
multi	users.toml（デフォルトは ~/.telegram/users.toml）に記載されたユーザー。それぞれ独自のトークンを使用します	各ユーザー固有の名前空間

telegram token hash を使ってトークンハッシュを作成します（トークンは標準入力またはプロンプトから読み込まれ、コマンドラインから読み込まれることはありません）。multi モードでユーザーを追加するには、users.toml を編集してサーバーを再起動します。

[users.alice]
token_hash = "scrypt$..."
enabled = true
namespace = "alice"

次に、サーバーマシン上でそのユーザーの Telegram を認証します。

telegram auth --phone +15551234567 --user alice

別のマシンにあるサーバーに接続するには、TLS 終端リバースプロキシまたはプライベートネットワークの背後に配置し、token または multi 認証を使用します。

CLI

telegram コンソールスクリプト（uvx / pip でインストール。better-telegram-mcp はレガシーエイリアスです）は、サブコマンドなしで実行すると MCP サーバーを起動します。サブコマンドではないフラグはサーバーに渡されます（例：--http、--host、--port）。

telegram            # start the MCP server (stdio)
telegram --http     # start in HTTP mode
telegram --version  # print the version

サブコマンド	使用方法	説明
auth	auth --bot-token <token> または auth --phone <+number>、任意で --user <ns>	このマシンを認証します。ボットモードではトークンを検証します。電話モードでは対話型の OTP／2FA フローを実行し、Telethon セッションをディスクに保存します
login	auth と同じ引数	auth の非推奨エイリアス
logout	logout [--yes] [--user <ns>]	Telegram セッションを失効させ、セッションファイルと保存済み認証情報を削除します
config	config status、config delete --yes	保存済みの認証情報設定を表示または削除します
status	status	認証情報が設定されているかどうかを表示します
doctor	doctor	環境診断情報を出力します
token	token hash	config.toml / users.toml 用にベアラートークンをハッシュ化します

--user は保存先の名前空間を選択します（デフォルトは default。stdio と no-auth / token HTTP モードで使用されます）。不明なサブコマンドはステータス 2 で終了します。

ツール

ツール	アクション	説明
message	send、edit、delete、forward、pin、react、search、history	メッセージの送信、編集、削除、転送を行います。メッセージのピン留め、リアクション、検索、履歴の閲覧もできます
chat	list、info、create、join、leave、members、admin、settings、topics	チャット、グループ、チャンネルを一覧表示して管理します。メンバー、管理者、フォーラムのトピックも扱います
media	send_photo、send_file、send_voice、send_video、download	写真、ファイル、ボイスメッセージ、動画を送信します。メッセージからメディアをダウンロードします
contact	list、search、add、block	連絡先を一覧表示、検索、追加します。ユーザーモードではユーザーのブロック／ブロック解除もできます
config	status、set、cache_clear	サーバーのステータス、実行時設定（message_limit、timeout）、キャッシュ
help	--	任意のトピックに関するドキュメント全体

MCP リソース

URI	内容
telegram://docs/messages	メッセージ操作のリファレンス
telegram://docs/chats	チャット管理のリファレンス
telegram://docs/media	メディアの送信／ダウンロードに関するリファレンス
telegram://docs/contacts	連絡先管理のリファレンス
telegram://stats	すべてのドキュメントをまとめたもの

比較

各項目において、telegram と直接の競合製品を比較します。

機能	telegram	chigwell/telegram-mcp	sparfenyuk/mcp-telegram	guangxiangdebizi/telegram-mcp
Bot API モード（ボットトークン）	対応（httpx）	非対応	非対応	対応
MTProto ユーザーアカウントモード	対応（Telethon）	対応	対応	非対応
メッセージの送信／編集／削除	対応	対応	非対応（読み取り専用、下書きのみ）	対応（送信のみ）
メッセージからのメディアのダウンロード	対応	対応	対応	非対応（送信のみ）
連絡先の管理（追加／ブロック）	対応（ユーザーモード）	対応	一部対応（一覧表示のみ）	非対応
マルチユーザー HTTP、ユーザーごとの分離	対応（ユーザーごとのトークンと名前空間）	非対応	非対応	非対応
SSRF 対策	対応（URL 検証＋DNS リバインディング対策）	?	?	非対応
パストラバーサル対策	対応	対応（実パスの許可ルート）	?	非対応
セルフホスト可能	対応	対応	対応	対応

セキュリティ

• SSRF 対策 -- すべての URL を内部／プライベート IP アドレス範囲と照合して検証し、DNS リバインディングをブロックします
• パストラバーサル対策 -- ファイルパスを検証し、機密ディレクトリへのアクセスをブロックします
• セッションファイルのセキュリティ -- 権限は 600 です。2FA パスワードは入力を求められ、環境変数には保存されません
• エラーのサニタイズ -- 認証情報とボットトークンがエラーメッセージやログに漏れることはありません
• プロンプトインジェクションの境界 -- ツールが返す Telegram のコンテンツは、信頼できないコンテンツを示すタグで囲まれます

ソースからビルド

git clone https://github.com/n24q02m/telegram.git
cd telegram
uv sync
uv run telegram

信頼モデル

このプロジェクトは、ホスト型の Telegram エンドポイントを運用していません。サーバーはお客様が管理するインフラストラクチャ上で動作し、認証情報がそのマシンの外部に出ることはありません。

データ	保存場所	保護
保存された認証情報（ボットトークン／電話番号）	~/.telegram/config.json。multi モードでは ~/.telegram/subs/<ns>/config.json	マシンキー ~/.telegram/.secret を使った AES-256-GCM 暗号化
Telethon セッション	~/.telegram/<name>.session。multi モードでは ~/.telegram/subs/<ns>/	ファイル権限 0600
HTTP ベアラートークン	config.toml／users.toml の token_hash	scrypt ハッシュのみを保存

OS ユーザーアカウントにアクセスできる人は誰でも、これらのファイルを読み取ることができます。

ライセンス

Apache-2.0 -- LICENSE を参照してください。