Telegram MCP — 次世代

MCP互換クライアント向けの実運用指向Telegram連携です。LoneVertex がメンテナンスし、Telethon と Model Context Protocol 上に構築されています。このリポジトリは上流のTelegram機能を維持しつつ、明示的なツール層、フェイルクローズの変更制御、キー付き並行性制限、上限付きリトライ、ローカルSQLite/FTS5キャッシュ、より安全なメディアパス、パッケージエントリポイント、再現可能なCIを追加しています。

デフォルトの基本方針: ローカル stdio、core ツール層、Telegram への書き込みなし、破壊的操作なし、検証されていない filesystem roots なし。

プロジェクト運営: Contributing · Security Policy · Apache License 2.0

含まれるもの

この実装は 128個のツール を登録します。アカウント、チャット、コンタクト、メッセージ、グループ、メディア、プロフィール、フォルダ、受信イベントをカバーする上流の125ツールに加え、cache_health、search_cached_messages、sync_chat_cache を含みます。上流の出自はコミット 52cca204d945e4ec292801a9d972334c0c2a4b63 に保持され、次世代パッケージのバージョンは 4.0.1 です。

TELEGRAM_MCP_TIER を設定して層を選択します。層の選択により登録されるツールが決まります。TELEGRAM_SEND_ENABLED は書き込み操作を実行できるかどうかを独立して制御し、TELEGRAM_DESTRUCTIVE_ENABLED は破壊的/管理操作のための第二のゲートです。サーバーは、いずれかのゲートが呼び出しをブロックすると、構造化された nothing_sent または nothing_done レスポンスを返します。

Related MCP server: telegram-mcp

クイックスタート

Python 3.11 または 3.12 を使用してください。my.telegram.org/apps から Telegram API の資格情報を取得し、同梱のセッション生成ツールを使って MCP プロセス外で承認済みセッションを生成してください。

git clone https://github.com/LoneVertex/telegram-mcp-nextgen.git
cd telegram-mcp-nextgen
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# edit .env with TELEGRAM_API_ID, TELEGRAM_API_HASH, and an authorized session
telegram-mcp

パッケージ開発とリリース検証のため:

pip install -e '.[dev]'
pytest -q
ruff check telegram_mcp/config.py telegram_mcp/core telegram_mcp/db telegram_mcp/models
mypy --explicit-package-bases telegram_mcp/config.py telegram_mcp/core telegram_mcp/db telegram_mcp/models
python -m build

サーバーは意図的に非対話式です。起動前に telegram-mcp-generate-session を使用し、生成されたセッション文字列を秘密に保ってください。.env、Telethon の .session ファイル、API ハッシュ、セッション文字列をコミットしないでください。

設定

シークレットなしの完全なテンプレートは .env.example にあります。主な設定を以下にまとめます。

設定の構築は副作用を伴いません。資格情報と認可の確認は、ローカルツールがパッケージをインポートするときではなく、ライブクライアントが起動するときに行われます。キャッシュやセッション操作が必要とする場合、ランタイム状態は所有者のみがアクセスできるディレクトリ配下に作成されます。

MCP クライアントとトランスポート

デスクトップ MCP クライアント向けのシークレットなしの例は config/mcp-configs.md を参照してください。ローカル stdio を推奨します。長期間実行されるローカルサービス向けには Streamable HTTP も利用できます。

MCP_TRANSPORT=http
MCP_HOST=127.0.0.1
MCP_PORT=8765

認証のない HTTP エンドポイントをパブリックインターネットに直接公開しないでください。リバースプロキシを使う場合は、認証、TLS、許可ホスト、許可オリジン、ネットワーク制御を設定してください。MCP_ALLOWED_HOSTS を設定している場合、サーバーは MCP DNS リバインディング保護を維持します。

並行性と信頼性

各アカウントは、キー付き async mutex とトークンバケットによって保護されます。同一アカウントを共有する呼び出しは、アダプター境界で直列化されます。一方で、異なるアカウントラベルにわたる読み取り専用のマルチアカウントファンアウトは可能です。FloodWait と一時的な接続障害は、指数バックオフとジッターを備えた上限付きの単一のリトライポリシーを使用します。セッションレベルのアドバイザリロックは維持され、同じ Telegram 認証キーを複数のプロセスが同時に使用するのを防ぎます。

ローカルキャッシュは、SQLite の WAL モード、外部キー、短時間の接続、明示的なトランザクション、チャット/日付/送信者/トピックのインデックス、検索用の FTS5 を使用します。同期処理はチェックポイントを保存し、upsert を使用するため、編集内容は重複せずに反映されます。SQLite の処理、ディレクトリ作成、整合性チェックは、イベントループをブロックせずにワーカースレッドで実行されます。

メディアとファイルシステムの安全性

ファイルツールは、クライアントの MCP Roots または明示的なサーバー側ルートを必要とします。空または検証できないルートは、TELEGRAM_ALLOW_SERVER_ROOTS_FALLBACK=true を意図的に有効にしない限り、すべて拒否する動作になります。パスは設定されたルート配下で解決され、侵入トラバーサルと NUL バイトは拒否され、シンボリックリンクによる境界外参照を拒否され、メディアサイズ制限が適用され、生成されたファイルは所有者のみのパーミッションを使用します。新しいセキュリティプリミティブは、チャンク読み取りとアトミックな出力置き換えをサポートしています。

Telegram のテキスト、キャプション、名前、ボタンラベル、メディアメタデータ、受信イベントフィールドは、信頼できないユーザーコンテンツです。サニタイズ処理とオーディエンス注釈は上流から引き継がれており、これらのフィールドを命令として扱ってはいけません。

Docker

イメージは 2 ステージの Python 3.12 ビルドを使用し、UID 10001 として実行し、状態を /var/lib/telegram-mcp に保持し、認証情報を実行時のみ受け取ります。

cp .env.example .env
# edit .env
podman compose up --build
# or: docker compose up --build

Compose は HTTP を 127.0.0.1:8765 にバインドし、永続的な名前付きボリュームを使用し、Linux ケイパーティを破棄し、no-new-privileges を有効にし、読み取り専用のルートファイルシステムをマウントし、制約付きの /tmp を提供します。コンテナビルドは Docker が利用できなかったため、今回の納品に使用したプロセス内では実行されていません。Docker をサポートするランナーで行われる CI ワークフローで検証されます。

開発とリリースのゲート

.github/workflows/ci.yml の集約ワークフローは、Python 3.11 と 3.12 で実行され、継承した回帰手順テストに加えて次世代のテストを実行し、新しいプロダクション層に対して厳格な Ruff チェックを実行し、明示的なパッケージベースの mypy チェックを実行し、パッケージをコンパイルし、wheel/sdist をビルドし、宣言された依存関係を監査し、Docker イメージと Compose 設定を検証します。上流のライブ Telegram アダプターは、継承したモック化回帰テストスイートで引き続きカバーされます。ローカルの信頼性/セキュリティモジュールには専用のテストとカバレッジがあります。

所有権、互換性、来歴

プロジェクトメンテナンス: LoneVertex。

ルートの main.py、上流ツールのモジュール名、セッション生成ツール、アカウントラベル、プロキシ設定、MCP トランスポート変数、従来の公開フィルター、上流の Apache-2.0 ライセンスは、互換性のために保持されています。新しいパッケージのエントリポイントは telegram_mcp.runner:main で、python -m telegram_mcp もサポートされています。上流のソースと帰属は Git 履歴と AUDIT_REPORT.md に表示されます。

トラブルシューティング

起動時にセッションが設定されていないと表示された場合は、承認済みセッションを生成し、TELEGRAM_SESSION_STRING または有効なファイルセッション名を設定してください。書き込みが MutationDisabled を返した場合は、TELEGRAM_SEND_ENABLED=true を設定して再起動してください。削除または管理操作の場合は TELEGRAM_DESTRUCTIVE_ENABLED=true も設定してください。ファイルツールがルートを利用できないと報告する場合は、クライアントの MCP Roots を設定するか、サーバー側で許可されたルートを引数の位置に指定してください。FloodWait が設定済みの最大値を超えた場合、無限に待機されるのではなく、呼び出しは意図的に返されます。cache_health を使うと、Telegram に接続せずにローカル SQLite/FTS5 の整合性を検査できます。

参照

ライセンス

アパッチ人は、Apache License 2.0 です。 LICENSE を参照してください。