Telegram MCP Server

Name: Telegram MCP Server
Author: tolboy

ローカル

github.com/tolboyコミュニケーション122 日前に更新

リポジトリ

Telegram MCP Server について

Telegram MCP Server は、TDLib を通じて AI エージェントを実際の Telegram ユーザーアカウントに接続します。初期状態は読み取り専用で、書き込みツールは任意で有効化でき、アカウント分離と破壊的操作の人間承認も備えています。

主な機能

01TDLib によるユーザーアカウント接続
02Telegram 操作用の 116 ツール
03読み取り専用の初期設定とプロファイル選択
04分離された複数アカウントセッション
05承認ゲートと再試行可能な送信
06STDIO と Streamable HTTP に対応

活用シーン

01個人の会話の要約と検索
02送信せずに返信を下書き
03書き込みを承認制にしたグループ管理
04権限を限定して複数アカウントを接続

MCP 対応

メッセージ、検索、連絡先、メディア、管理機能などを MCP ツールとして提供します。STDIO と `/mcp` の Streamable HTTP に対応します。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "tolboy-telegram-mcp-tdlib": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TDLIB_API_ID",
        "-e",
        "TDLIB_API_HASH",
        "-e",
        "TDLIB_PHONE_NUMBER",
        "-e",
        "TDLIB_AUTH_CODE",
        "-e",
        "TDLIB_2FA_PASSWORD",
        "-e",
        "MCP_READ_ONLY",
        "-e",
        "MCP_TOOL_PROFILE",
        "ghcr.io/tolboy/telegram-mcp-tdlib:1.18.0-stdio"
      ],
      "env": {
        "TDLIB_API_ID": "<TDLIB_API_ID>",
        "TDLIB_API_HASH": "<TDLIB_API_HASH>",
        "TDLIB_PHONE_NUMBER": "<TDLIB_PHONE_NUMBER>",
        "TDLIB_AUTH_CODE": "<TDLIB_AUTH_CODE>",
        "TDLIB_2FA_PASSWORD": "<TDLIB_2FA_PASSWORD>",
        "MCP_READ_ONLY": "<MCP_READ_ONLY>",
        "MCP_TOOL_PROFILE": "<MCP_TOOL_PROFILE>"
      }
    }
  }
}

起動コマンド

docker run -i --rm -e TDLIB_API_ID -e TDLIB_API_HASH -e TDLIB_PHONE_NUMBER -e TDLIB_AUTH_CODE -e TDLIB_2FA_PASSWORD -e MCP_READ_ONLY -e MCP_TOOL_PROFILE ghcr.io/tolboy/telegram-mcp-tdlib:1.18.0-stdio

設定が必要な環境変数

TDLIB_API_IDTelegram API ID from my.telegram.org

TDLIB_API_HASHシークレットTelegram API hash from my.telegram.org

TDLIB_PHONE_NUMBERシークレットTelegram phone number; omit after preparing a persisted session when using QR authentication

TDLIB_AUTH_CODEシークレットOne-time Telegram login code for a fresh headless container

TDLIB_2FA_PASSWORDシークレットTelegram 2FA password when the account requires it

MCP_READ_ONLYKeep true for safe first use

MCP_TOOL_PROFILETool surface: reader, inbox, community-admin, research, or all

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

ocighcr.io/tolboy/telegram-mcp-tdlib:1.18.0-stdiostdio

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

Telegram MCP サーバー

実アカウント向け Telegram MCP — デフォルトで安全、TDLib を採用し、本番環境に対応しています。

ローカルファーストのModel Context Protocolサーバーです。アカウントの鍵を渡すことなく、AI エージェントから実際の Telegram アカウントにアクセスできます。初期状態では読み取り専用で起動し、オプトインするまで書き込みツールを非表示にします。デスクトップクライアント向けにはSTDIO、管理されたデプロイメント向けには/mcpでStreamable HTTPを使用します。

このサーバーの特長

デフォルトで安全 — 小規模なinbox／readerプロファイルを使う読み取り専用モードで起動します。書き込みツールやクォータを消費するツールは、使用を有効にするまでモデルから非表示になります。単に呼び出しをブロックするだけではありません。
クライアントに依存しない人間の承認 — 破壊的なツールは、まず人間に確認を求めます。エリシテーションに対応している場合は MCP ホストを通じて、そうでない場合はこのサーバーがホストする使い捨てのループバックページを通じて確認します。いずれの場合も、質問はモデルのターン外で送信され、回答もモデルのターン外で返されます。そのため、注入された指示によってモデルに禁止を要求させることはできても、承認させることはできません。
エージェントが再試行できる送信 — idempotency_keyを使うと、応答が失われた場合でも重複メッセージを送信せず、保存されたレシートを返します。確認できていない送信はUNKNOWNとして報告され、黙って再送されることはありません。
ボットだけでなく実際のユーザーアカウントに対応 — TDLib（tdlight-java 経由）を基盤としているため、Bot API の一部機能だけでなく、実際のアカウントをエージェントが読み取り、操作できます。
複数アカウントを分離 — アカウントごとに独自のセッションと必須の選択手順があり、API キーも個別にスコープされます。読み取りが複数のアカウントにまたがることはありません。
2 種類のトランスポート — Claude Desktop／Cursor／VS Code／Codex 向けの STDIO と、管理サービス向けの Streamable HTTP を利用できます。
JDK のインストール不要 — Windows、Linux x64／ARM64、Apple シリコン搭載 macOS 向けに、ランタイム同梱のリリースバンドルを提供します。チェックサム、SBOM、署名済みコンテナダイジェストも含まれます。

画像は説明用のモックアップです。実際のスクリーンキャストは近日公開予定です。

安全な初回起動

ランタイム同梱のリリースには、JDK、Gradle、Git、Python、Node.js は不要です。可能であれば、初回はテストアカウントをご使用ください。

1. インストール（Apple シリコン搭載 macOS／Homebrew を使用した Linux）：

brew install --formula https://github.com/tolboy/telegram-mcp-tdlib/releases/latest/download/telegram-mcp.rb

Scoop を使用した Windows：

scoop install https://github.com/tolboy/telegram-mcp-tdlib/releases/latest/download/telegram-mcp.json

2. ログイン QR コードをスキャンします。ワンタイムコードがシェルの履歴に残ることはありません。

telegram-mcp auth --method qr

3. セッションの確認 セッションが準備完了であることを確認します。ローカルの状態を読み取るだけで、サーバーは起動しません。

telegram-mcp session doctor

試しにserve --transport stdioを自分で実行しないでください。STDIO では AI クライアントがサーバーを起動し、そのライフサイクルを管理します。ターミナルから起動したプロセスが TDLib セッションを保持するため、クライアント側のプロセスはtd.binlogをロックできず、終了コード 2 で終了します。代わりに（以下のように）コマンドをクライアントに渡し、クライアントに起動させてください。

まずは、何も変更できない最初のプロンプトを試してください。

「直近 20 件の会話を要約してください。送信も変更もしないでください。」

このモードでは、書き込みツールやクォータを消費するツールはツール一覧に一切表示されないため、モデルが破壊的な操作を呼び出すことはできません。機能の範囲を確認してから、MCP_READ_ONLY=falseに切り替えてください。その際はMCP_DESTRUCTIVE_APPROVAL=autoも設定してください。これにより、削除、禁止、退出の操作は、モデル自身の"confirmed": trueを信頼するのではなく、対応している場合はホストのエリシテーションを通じて、そうでない場合はサーバーのループバックページを通じて、あなたの回答を待つようになります。

クライアントを接続する

手入力する代わりにエントリを生成しましょう。クライアントが実際に必要とするキーを入力し、生成時のバージョンを固定します。

telegram-mcp config --client claude

--client claude-code|cursor|vscode|codex で対象を切り替えます。Codex には TOML を、VS Code には実際に読み込まれる servers キーを、Claude Code には明示的なトランスポートの type を生成します。--writes を指定すると、書き込みツールと、破壊的な操作を保護する承認プロンプトが有効になります。書き込みに対応する --profile inbox|community-admin|all と組み合わせてください。デフォルトの reader サーフェスでは、読み取り専用モードが確認される前に書き込みツールが非表示になるためです。--docker default は、イメージを固定したコンテナーエントリを生成し、--http default は Claude Code、 Cursor、VS Code、Codex 用の共有デーモンエントリを生成します。Claude Desktop は claude_desktop_config.json からリモートサーバーを読み込みません。代わりに「設定」→「コネクター」から、ネットワーク経由で接続可能なリモートエンドポイントを追加してください。Claude のリモートコネクターは、ジェネレーターが設定するカスタム API キーヘッダーを受け付けないため、このサーバーは MCP_AUTH_MODE=oauth を使って HTTPS 経由で公開する必要があります。そのため、ジェネレーターは --client claude --http を拒否します。

STDIO はデスクトップクライアントにとって、手軽に始められる方法です。生成されるエントリは次のようになります。

{
  "mcpServers": {
    "telegram": {
      "command": "telegram-mcp",
      "args": ["serve", "--transport", "stdio"],
      "env": {
        "TDLIB_API_ID": "123456",
        "TDLIB_API_HASH_FILE": "/absolute/path/to/telegram-api-hash",
        "MCP_TOOL_PROFILE": "inbox",
        "MCP_READ_ONLY": "true"
      }
    }
  }
}

Claude Desktop — 上記のブロックを claude_desktop_config.json に追加し、タスクトレイからアプリを終了して、再起動してください。「設定」→「開発者」→「設定を編集」を使うと、ファイルを開けます。使用中のビルドに対応した場所が表示されます。%APPDATA%\Claude を手動で編集する方法が使えるのは、インストーラービルドのみです。Microsoft Store 版は MSIX としてパッケージ化されており、代わりに設定は %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\ に保存されます。
Cursor — ~/.cursor/mcp.json に追加します（または「設定」→「MCP」→「追加」）。
VS Code — .vscode/mcp.json を使用します。VS Code ではトップレベルのキーが mcpServers ではなく servers であり、明示的な "type": "stdio" または "type": "http" が必要です。

クライアント間で 1 つのローカルプロセスを共有するには、telegram-mcp daemon start と telegram-mcp daemon attach --client cursor（または codex、vscode、claude-code）を使用します。ステータス、停止、オンボーディングについては、管理対象のローカルデーモンを参照してください。

STDIO の代わりに管理対象の HTTP デプロイを行う場合：

docker run --rm -p 127.0.0.1:8080:8080 \
  -e TDLIB_API_ID -e TDLIB_API_HASH -e MCP_API_KEY \
  ghcr.io/tolboy/telegram-mcp-tdlib:latest

プラットフォームやクライアントごとの正確なバリエーションについては、CLI と STDIO、対話型認証、クライアントの互換性を参照してください。

レシピ

再利用可能なエージェント向けの指示には、無料の Telegram Inbox Assistant スキルをインストールしてください。サーバー 1.17.2 以降が必要です。共有デーモンを使用する Claude Desktop ユーザーは、オプションのツールブリッジを利用できます。これは、 Python の依存関係に関する手順とともにランタイムパッケージに含まれています。セットアップガイドには、クライアントの設定テンプレートが含まれており、ローカルサーバーと Telegram の認証が別途必要であることも説明しています。このスキルは、読み取り専用モードで要約と検索を行います。

実際のタスクに使える、コピーして貼り付けるだけの設定とプロンプトを紹介します。それぞれ、タスクを実行できる最小限のツール構成になっています。受信トレイを要約する、失くしたメッセージを探す、公開グループを調査する、読み取り専用のコミュニティ健全性チェック、送信せずに返信の下書きを作成する — 一覧はdocs/recipesを参照してください。

比較

多くの Telegram MCP サーバーは、Bot API または Telethon のユーザーセッションをラップし、すべての機能を一度にモデルへ公開します。このプロジェクトは、エージェントを大切な実アカウントへ安全に接続することを重視しています。

項目	このサーバー	一般的な Telethon／Bot-API MCP サーバー
アカウントへのアクセス	TDLib（tdlight-java）経由の実ユーザーアカウント	多くの場合、ボット専用、または単一の Telethon ユーザーセッション
デフォルトの状態	読み取り専用。書き込み／クォータ関連ツールは有効にするまで非表示	通常、最初からすべてのツールを公開
複数アカウント	セッションを分離し、選択を必須とし、キーをスコープ化。アカウントをまたいだ一括読み取りなし	単一アカウント、または暗黙的な一括読み取り
トランスポート	STDIO および Streamable HTTP `/mcp`	通常は STDIO のみ
安全策	確認による制御、監査ログ、スパム対策の制限、チャットの許可リスト、信頼できないコンテンツのマーキング	最小限
配布	署名済みランタイムバンドル（JDK 不要）、SBOM と来歴情報、GHCR イメージ	pip／npx によるソースのインストール

より詳しいアーキテクチャの比較（TDLib と Telethon と Bot API の比較、「ブロックせず非表示にする」ことが重要な理由）は、docs/COMPARISON.md をご覧ください。主要な公開サーバーとの、日付入りの詳細なベンチマーク（意図的に採用を見送った機能、つまり raw MTProto のエスケープハッチ、所有権の移転、一括連絡先エクスポートを含む）は、PUBLIC_BENCHMARK_AND_ROADMAP.md をご覧ください。

ツールプロファイル

最初から 116 個のツールを公開する必要はありません。MCP_TOOL_PROFILE は、クライアントがツールを目にする前に公開範囲を絞り込みます。アカウントのスコープ制御、読み取り専用モード、確認、監査、スパム対策は弱まりません。

プロファイル	公開範囲
`reader`	常に変更を伴わないため、最初に試すのに安全です
`inbox`	個人メッセージ、下書き、メディア、連絡先、プライバシー
`community-admin`	モデレーション、グループ／チャンネル、権限、ボットコマンド
`research`	範囲を限定したアカウント／公開情報の探索と閲覧
`all`	すべてのツール（意図的に有効化する場合）

各公開範囲の具体的な目的については、TOOL_PROFILES.md をご覧ください。

機能

116 個の MCP ツール — メッセージ、投票、既読通知、予約送信、チャット、フォルダー、招待リンクの管理、連絡先、メディア、下書き、プライバシー、ボットコマンド、詳細なグループ権限、プロフィール、検索、アカウントの振り分けに対応します。
tdlight-java 経由の TDLib — Bot API だけでなく、実際のユーザーアカウントを利用します。
分離されたマルチアカウントモード — 独立したセッション、必須のアカウント選択、キーごとに任意で設定できるアカウントスコープに対応し、複数アカウントをまたぐ読み取りは行いません。
デフォルトで安全 — 読み取り専用のツールセット、破壊的な操作に対する人間の承認（ホスト経由またはループバックページ経由の MCP_DESTRUCTIVE_APPROVAL）、タスクに特化したプロファイル（reader/inbox/community-admin/research/all）を備えています。
復旧可能な送信 — テキスト、返信、ファイル、音声、ステッカー、転送、予約メッセージに対し、任意の冪等性キーと永続的な受領記録を利用できます。送信の復旧をご覧ください。
クライアントごとの権限 — レビュー済みの JSON ファイルで、各クライアントに名前付きアカウントとチャットに対する read、download、mutate、quota、policy の各操作を許可します。それ以外の操作はすべて拒否されます。権限をご覧ください。
エージェントが信頼できる回答 — すべてのツールが型付き出力スキーマを公開し、エラーには再試行の指針を含む安定したコードが付与され、エクスポートと検索では結果が不完全な場合にその旨が示されます。
長時間実行する作業 — 応答予算を設定できる簡潔な受信トレイおよび会話ツール、再起動後に再開できるエクスポート、自身の欠落を報告する変更ジャーナルを備えています。
2 種類のトランスポート — デスクトップクライアント向けの STDIO と、API キー認証に対応した Streamable HTTP /mcp（Spring AI 2.0 / MCP SDK 2.0）を利用できます。telegram-mcp daemon では、複数のクライアントで 1 つのローカルサーバーを共有できます。
ガードレール — 監査ログ、Resilience4j レートリミッター（30 req/s）とサーキットブレーカーによるスパム対策、チャットの許可リスト、プロンプトインジェクションのパターン検出、信頼できないコンテンツのマーキングを備えています。
可観測性 — Micrometer メトリクス、Prometheus エンドポイント、MDC（traceId、sessionId、toolName）を含む構造化 JSON ログを利用できます。
検証済みのランタイム同梱リリース — Windows x64、Linux x64/ARM64、Apple シリコン搭載 macOS 向けバンドルを、チェックサム、SBOM、署名済みコンテナダイジェストとともに提供します。JDK は不要です。

その他の機能

エンティティ解決 — @username、+phone、数値 ID を透過的に解決します。
MCP の動作アノテーション — 公開されるすべてのツールで、読み取り専用、破壊的操作、再試行、オープンワールドのヒントを宣言し、クライアントの UX をより安全にします。
構造化・マーキング付き出力 — 後方互換性のある JSON テキストと structuredContent を提供します。Telegram が制御するフィールドは明示的に信頼できないものとして扱い、表示制御用の Unicode はエスケープされます。
ホストに適したディスカバリー — インストーラー、デスクトップホスト、サービスマネージャー向けに /.well-known/mcp-server.json を提供します。
安全なメディアアップロードのためのファイルセキュリティサービス、Actuator によるヘルス／情報／メトリクス、設定可能なタイムアウトを備えたグレースフルシャットダウン。
マルチステージの Docker ビルドと、開発時のホットリロードに対応する docker-compose。
ランタイム同梱のアプリイメージ — 対応するリリースアーカイブには独自の Java ランタイムが含まれ、公開前に実際の STDIO ハンドシェイクに合格します。
オフラインのセッション診断ツール — TDLib を起動したり秘密情報を出力したりせずに、設定済みの TDLib 状態パスとロックの利用可否を確認します。
クリーンアーキテクチャ — config / model / client / service / tool / security / util / exception。
言語に依存しない公開検索 — 呼び出し側は、同義語、翻訳、綴りの異なる表記を任意の言語で渡せます。製品固有のポリシー解釈は MCP ホスト側で行います。

## 技術スタック

コンポーネント	バージョン
Java	25
Kotlin	2.4.21
Spring Boot	4.1.1
Spring AI MCP	2.0.1
MCP Java SDK	2.1.0
TDLib (tdlight)	3.5.9+td.1.8.68
Gradle	9.8.2
Resilience4j	2.4.0

クイックスタート

前提条件

Java 25 以降（または Docker を使用）
https://my.telegram.org から取得した Telegram API 認証情報（TDLIB_API_ID、TDLIB_API_HASH）
認証モードを必ず 1 つだけ選択してください。ユーザーアカウントモードでは TDLIB_PHONE_NUMBER、ボットモードでは TDLIB_BOT_TOKEN を使用します。

1. クローンして設定する

git clone https://github.com/tolboy/telegram-mcp-tdlib.git
cd telegram-mcp-tdlib
cp .env.example .env
# Edit .env — set TDLIB_API_ID, TDLIB_API_HASH, one of TDLIB_PHONE_NUMBER/TDLIB_BOT_TOKEN, and MCP_API_KEY

Windows PowerShell では、cp の代わりに Copy-Item .env.example .env を使用してください。

2. ローカルで実行する

./gradlew bootRun

サーバーは http://localhost:8080 で起動します。MCP Streamable HTTP エンドポイントは http://localhost:8080/mcp です。

最初の 60 秒

クライアントにリモートの Streamable HTTP MCP サーバーを追加し、URL に http://127.0.0.1:8080/mcp、認証に Authorization: Bearer <MCP_API_KEY> を指定します。 Cursor、VS Code、Codex、Claude Code、Inspector は、このローカル HTTP エンドポイントを使用できます。Claude Desktop の設定ファイルでは上記のローカル STDIO エントリを使用できます。リモートコネクターは「設定」→「コネクター」から追加します。この場合、ループバック URL とカスタムヘッダーではなく、MCP_AUTH_MODE=oauth を使用した、ネットワークから到達可能な HTTPS エンドポイントが必要です。接続の詳細は MCP_CLIENT_COMPATIBILITY.md を参照してください。
MCP_READ_ONLY=true と、範囲を絞った 1 つのサーフェス（例： MCP_TOOL_PROFILE=inbox または MCP_TOOL_PROFILE=research）を指定して、安全に始めます。
クライアントに、次のような具体的な質問をしてみます。
- 受信トレイ：「関連する最近の会話を 20 件要約してください。送信や変更はしないでください。」
- コミュニティ：「このグループの最近の管理操作とデフォルトの権限を表示してください。変更案を提示してください。ただし適用はしないでください。」
- リサーチ：「英語とロシア語の検索語句のバリエーションに一致する公開チャットを見つけ、説明と最近のメッセージに基づく根拠を報告してください。」

検出されたサーフェスを確認してから、MCP_READ_ONLY=false に切り替えてください。破壊的な操作では、デフォルトで引き続き確認が有効です。

Windows では、同期フォルダーでのファイルロックの問題を避けるため、Gradle の出力先はデフォルトでシステムの一時ディレクトリになります。KTM_BUILD_DIR を設定するか、-Pktm.buildDir=... を指定して上書きしてください。

3. Docker で実行する

docker compose up --build

compose スタックは、TDLib のセッションデータを tdlib-data ボリュームに、ダウンロードデータを telegram-downloads に保持します。また、${MCP_UPLOADS_DIR:-./docker-data/uploads} をコンテナ内の /data/uploads にマウントし、アップロード／ダウンロードツールで使用します。

デフォルトでは、ローカルのボックス環境や開発環境が誤って LAN に公開されないよう、compose は MCP_BIND_HOST を介してサービスを 127.0.0.1 にバインドします。

ホットリロードを有効にした開発モード：

docker compose --profile dev up telegram-mcp-dev

Prometheus によるモニタリングを有効にする場合：

docker compose --profile monitoring up

本番環境に関する注意：コンテナの前段で TLS を終端してください（リバースプロキシ、イングレス、またはロードバランサーを使用）。API キーが、信頼できるローカル開発ネットワークの外で暗号化されていない HTTP を通過しないようにしてください。

ローカルのボックス型インストールとリモート／VPS への公開に関するデプロイ手順は、docs/DEPLOYMENT_MODES.md に記載されています。

マルチサーバー MCP ホストまたはインストーラーでのコネクター検出については、docs/CONNECTOR_DISCOVERY.md に記載されています。

クライアント互換性、移植可能な JSON-Schema プロファイル、Streamable HTTP のスモークテストについては、MCP_CLIENT_COMPATIBILITY.md に記載されています。

オフラインでも安全に行える TDLib セッションの検査とクリアについては、SESSION_MAINTENANCE.md に記載されています。

主要な公開 Telegram MCP サーバーとの比較と、優先度を付けた今後の作業については、PUBLIC_BENCHMARK_AND_ROADMAP.md に記載されています。

リリース

CI は、すべてのプルリクエストと master へのプッシュごとに実行されます。承認済みのリリースは vX.Y.Z 形式の Git タグです。リリースワークフローではイメージをビルドし、プッシュ済みのダイジェストに対してクロスプラットフォームのツールサーフェスのスモークテストとコンテナライフサイクルの契約テストを実行して、証明書を生成して署名します。その後に限り、公開タグ（latest、X.Y.Z、X.Y、不変の sha-<commit>、および -stdio バリアント）をその正確なダイジェストに付け替え、各タグがそのダイジェストを参照していることを検証します。Windows x64、Linux x64/ARM64、macOS ARM64 向けのリリースバンドルも併せて提供されます。公開リリースには、実行可能な JAR の SPDX SBOM、リリースアセットの GitHub provenance 証明、コンテナダイジェストのキーレス Sigstore 署名と provenance が含まれます。リリースバンドルの検証を参照してください。

再現可能なデプロイには、具体的な semver タグを使用してください。v1.0.0 は Streamable HTTP / MCP SDK 2.0 の最初の公開ベースラインです。v1.1.0 ではアカウントの分離、スコープ付きキー、クロスプラットフォームのネイティブパッケージングが追加されました。v1.2.0 ではプレミアム音声メモの文字起こしと中立的なパッケージ名前空間が追加されました。v1.3.0 ではプライバシー、ボットコマンド、詳細なグループ権限の制御、検証済みリリースバンドルが追加されました。v1.4.0 では用途に特化した MCP ツールプロファイルが追加されました。v1.7.x では STDIO トランスポート、対話型認証ウィザード付き CLI、構造化ツール出力、任意の OAuth リソースサーバーモード、ランタイムを含むリリースイメージが追加されました。v1.13.0 では、ホストまたはループバックページを介した破壊的ツールの実行に人間の承認を追加し、クライアントエントリーを生成する telegram-mcp config を追加しました。v1.14.0 では、公開されるすべてのイメージタグが検証と署名に合格したダイジェストに紐付けられます。v1.15.0 では、コネクター自身の応答から実行中のビルドを確認できるようになりました。v1.16.0 では、対話型ログインを修正しました。認証リクエストが実際に TDLib に届き、2 回目のログイン試行でプロセスが中断されなくなり、認証状態に Telegram がコードを送信した宛先が示されます。v1.17.0 では、キー付き送信の復旧、クライアントごとの権限、構造化エラー付きの全ツールの型付き出力、コンパクトなタスクツール、変更ジャーナル付きの再開可能なエクスポート、管理対象のローカルデーモンが追加されました。全履歴は CHANGELOG.md にあります。

実際に応答しているリリースを確認するには、_manifest ツールを呼び出してください。応答には schemaVersion とともに serverVersion が含まれます。この値は JAR 独自のビルドメタデータ（リリースタグから導出された Gradle バージョン）から読み取られるため、MCP_SERVER_VERSION で書き換えることはできません。同じアーティファクトで telegram-mcp version を実行した場合も、同じ文字列が出力されます。

現在の TDLight ネイティブリリースでは、Apple シリコン搭載 macOS 向けのバイナリは公開されていますが、Intel macOS 向けの classifier は公開されていません。サーバーは JVM／パスのレベルでは Intel macOS をサポートしていますが、そのプラットフォームで TDLib を利用した Telegram アクセスを実行するには、上流のネイティブパッケージが必要です。

現在のプラットフォームに対応するランタイム込みアプリイメージを作成するには、次を実行します。

./scripts/package-app-image.ps1 -Version <version> -Target windows-x64 -OutputDirectory release-assets

ビルドでは、実際の BOOT-INF/lib の内容、ランチャーが報告するバージョン、ライブの STDIO ハンドシェイクを検証します。ターゲットの一覧は RELEASE_BUNDLES.md を参照してください。

git checkout master
git pull --rebase origin master
git tag -a vX.Y.Z -m "Telegram MCP Server vX.Y.Z"
git push origin master vX.Y.Z

環境変数

TDLib（主要な Telegram クライアント）

変数	必須	デフォルト	説明
`TDLIB_API_ID`	はい*	—	https://my.telegram.org の API ID
`TDLIB_API_HASH`	はい*	—	https://my.telegram.org の API ハッシュ
`TDLIB_API_HASH_FILE`	いいえ	—	`TDLIB_API_HASH` のシークレットファイルによる代替
`TDLIB_PHONE_NUMBER`	いいえ†	—	ユーザーアカウントモード（API の全アクセス権）用の電話番号
`TDLIB_BOT_TOKEN`	いいえ†	—	ボットモード用のボットトークン
`TDLIB_BOT_TOKEN_FILE`	いいえ	—	ボットトークンのシークレットファイルによる代替
`TDLIB_2FA_PASSWORD`	いいえ	—	2FA パスワード（ヘッドレス起動時に指定）
`TDLIB_2FA_PASSWORD_FILE`	いいえ	—	2FA パスワードのシークレットファイルによる代替
`TDLIB_AUTH_CODE`	いいえ	—	1 回限りのログインコード（初回のヘッドレス起動時に指定）
`TDLIB_AUTH_CODE_FILE`	いいえ	—	認証コードのシークレットファイルによる代替
`TDLIB_DATA_DIR`	いいえ	OS のアプリデータディレクトリ	セッションデータベースのディレクトリ
`TDLIB_DOWNLOADS_DIR`	いいえ	（データディレクトリ内）	ダウンロードしたメディアのディレクトリ
`TDLIB_LOG_VERBOSITY`	いいえ	`1`	TDLib ネイティブログの詳細度（0～10）
`TDLIB_SYSTEM_LANGUAGE_CODE`	いいえ	`en`	Telegram セッションで通知される言語コード
`TDLIB_DEVICE_MODEL`	いいえ	`Telegram MCP Server`	Telegram セッション設定に表示される、識別可能なデバイス名
`TDLIB_PROXY_TYPE`	いいえ	—	`socks5`、`http`（HTTP CONNECT）、または `mtproto`
`TDLIB_PROXY_SERVER` / `TDLIB_PROXY_PORT`	プロキシ使用時	—	プロキシのホスト名/IP アドレスとポート
`TDLIB_PROXY_USERNAME`	いいえ	—	SOCKS5/HTTP プロキシのユーザー名（パスワードも必要）
`TDLIB_PROXY_PASSWORD` / `_FILE`	いいえ	—	SOCKS5/HTTP プロキシのパスワード。`_FILE` はマウントしたシークレットによる代替
`TDLIB_PROXY_SECRET` / `_FILE`	MTProto のみ	—	MTProto シークレット。`_FILE` はマウントしたシークレットによる代替
`TDLIB_PROXY_HTTP_ONLY`	いいえ	`false`	HTTP プロキシを HTTP リクエストに限定します。通常は CONNECT のため `false` のままにします

* TDLib 統合を有効にする場合は必須です。
† TDLIB_PHONE_NUMBER または TDLIB_BOT_TOKEN のどちらか一方だけを設定してください。

非対話型認証：新しいコンテナでは、TDLIB_AUTH_CODE を 1 回設定してください（2FA が有効な場合は TDLIB_2FA_PASSWORD も設定します）。セッションが TDLIB_DATA_DIR に保存された後は、再起動時にどちらも不要です。直接指定するシークレット設定にはそれぞれ、Docker/Podman/Kubernetes のシークレットマウント向けに、相互排他的な *_FILE による代替設定があります。

ワンタイムコードを環境変数に指定せずにローカルで初回ログインする場合は、 INTERACTIVE_AUTH.md に記載されている電話番号/コード方式または QR 方式を使用してください。TDLIB_DEVICE_MODEL と TDLIB_SYSTEM_LANGUAGE_CODE は、Telegram の 設定 → デバイス に表示される識別可能なセッション情報を制御します。

保存データの暗号化に関する注意：SimpleTelegramClient（tdlight-java）では TDLib データベース暗号化キーを公開していません。本番環境では、ライブラリレベルのフラグに頼るのではなく、ファイルシステムレベル（LUKS、FileVault、EFS）で TDLIB_DATA_DIR ボリュームを暗号化してください。追加の use-file-database、use-chat-info-database、use-message-database の切り替え設定は、TdLibProperties.kt で利用できます。

Telegram プロキシ

サーバーはログイン前に TDLib 独自のプロキシを設定するため、初回認証と通常の Telegram 通信の両方に適用されます。次の完全な設定のいずれかを使用してください。不完全または無効なプロキシ設定の場合、アカウントが接続する前に起動が失敗します。

# SOCKS5 with optional username/password authentication
TDLIB_PROXY_TYPE=socks5
TDLIB_PROXY_SERVER=proxy.example.net
TDLIB_PROXY_PORT=1080
TDLIB_PROXY_USERNAME=connector
TDLIB_PROXY_PASSWORD_FILE=/run/secrets/telegram_proxy_password

# HTTP CONNECT (set HTTP_ONLY=false to route all TDLib traffic through it)
# TDLIB_PROXY_TYPE=http
# TDLIB_PROXY_SERVER=proxy.example.net
# TDLIB_PROXY_PORT=3128
# TDLIB_PROXY_HTTP_ONLY=false

# MTProto (secret must be supplied directly or through *_FILE)
# TDLIB_PROXY_TYPE=mtproto
# TDLIB_PROXY_SERVER=proxy.example.net
# TDLIB_PROXY_PORT=443
# TDLIB_PROXY_SECRET_FILE=/run/secrets/telegram_mtproto_secret

名前付きアカウントでは、TELEGRAM_ACCOUNTS_<LABEL>_PROXY_* を使用して個別に設定できます。たとえば、TELEGRAM_ACCOUNTS_WORK_PROXY_TYPE=socks5 のように指定します。アカウントのプロキシ設定で、別のアカウントの認証情報や TDLib セッションにフォールバックすることはありません。Docker 内で *_FILE を使用する場合は、シークレットファイルをコンテナにマウントし、コンテナ内のパスを設定してください。

サーバーとセキュリティ

変数	必須	デフォルト	説明
`TELEGRAM_BOT_TOKEN`	いいえ	—	旧式の Bot API トークン（フォールバックのみ）
`TELEGRAM_BOT_USERNAME`	いいえ	—	ボットのユーザー名（ログ用）
`TELEGRAM_ALLOWED_CHAT_IDS`	いいえ	（すべて許可）	許可するチャット ID（カンマ区切り）
`MCP_API_KEY`	リモート API キーモード*	—	MCP エンドポイント認証用 API キー
`MCP_API_KEY_FILE`	いいえ	—	`MCP_API_KEY` の代替となるシークレットファイル
`MCP_AUTH_HEADER`	いいえ	`Authorization`	API キー用のヘッダー名
`MCP_READ_ONLY`	いいえ	`true`	書き込み／変更を行うツールをブロックします。ローカルへのダウンロードには、以下の個別のオプトイン設定があります
`MCP_READ_ONLY_ALLOW_DOWNLOADS`	いいえ	`false`	読み取り専用モードおよびリーダー／リサーチプロファイルでのローカルな `download_media` を許可します。チャット／アカウントへのアクセスチェックは維持します
`MCP_PERMISSIONS_FILE`	いいえ	空	クライアント／アカウント／アクション／チャットへのアクセスを許可する、レビュー済みの JSON ファイル。権限設定とローカルエディターを参照してください
`MCP_TOOL_PROFILE`	いいえ	`reader`	`all`、`reader`、`inbox`、`community-admin`、または `research`
`MCP_TOOL_ALLOW`	いいえ	（プロファイルのツール）	プロファイルによるフィルタリング後に残す、正確なツール名（カンマ区切り）
`MCP_TOOL_DENY`	いいえ	—	許可リスト適用後に非表示にする、正確なツール名（カンマ区切り）
`MCP_TRANSPORT`	いいえ	`streamable-http`	`streamable-http` または `stdio`。CLI の `--transport` が優先されます
`MCP_CONFIRMATION_REQUIRED`	いいえ	`true`	破壊的なツールには、呼び出し元による確認（`"confirmed": true`）を必須にします。人間の承認を証明するものではありません
`MCP_DESTRUCTIVE_APPROVAL`	いいえ	`off`	`auto` は、各破壊的ツールの実行前に人間へ確認を求めます。対応している場合は MCP ホスト経由で、そうでない場合はループバックページで確認します。`elicitation`、`loopback` も指定できます
`MCP_DESTRUCTIVE_APPROVAL_TIMEOUT`	いいえ	`120s`	ループバックページでの回答期限です。エリシテーションでは MCP ホスト／リクエストの期限を使用します
`MCP_FILE_ROOTS`	いいえ	（すべて拒否）	ファイル操作で許可するルートディレクトリ
`MCP_AUDIT_ENABLED`	いいえ	`true`	監査ログを有効にします
`MCP_AUDIT_LOG_ARGS`	いいえ	`false`	監査ログにツールの引数を含めます
`MCP_AUDIT_FILE`	いいえ	—	追記専用の任意の JSONL 監査ログです。永続化された暗号化ボリュームを使用してください
`MCP_BIND_HOST`	いいえ	`127.0.0.1`	docker-compose のポート公開で使用するホストインターフェース
`MCP_AUTH_MODE`	いいえ	`api-key`	HTTP デプロイ向けの `api-key` またはオプトイン式の外部 `oauth`
`SERVER_PORT`	いいえ	`8080`	HTTP ポート
`SERVER_ADDRESS`	いいえ	`127.0.0.1`	組み込み HTTP のバインドアドレスです。API キーまたは OAuth による保護がある場合のみ、ループバック以外の値を設定してください

* API キーモードで空欄の場合、保護されたエンドポイントが受け付けるのは直接のループバックリクエストのみです。/mcp、/actuator/metrics、/actuator/prometheus へのループバック以外からのリクエストは拒否されます。コンテナーイメージは自身のネットワーク名前空間内でバインドされるため、公開ポートまたは Docker ブリッジ経由で MCP にアクセスするには、API キーまたは OAuth ベアラー認証による保護が必要です。

Compose 専用の便利な変数：

MCP_UPLOADS_DIR は、コンテナー内の /data/uploads にマウントするホストディレクトリを指定します。
KTM_BUILD_DIR は、プロジェクトのデフォルトを変更せずに、ローカルビルド用の Gradle ビルドディレクトリを上書きします。

ツールプロファイル

MCP_TOOL_PROFILE は、クライアントに表示される前に公開範囲を絞り込みます。アカウントのスコープ、許可リスト、読み取り専用モード、確認、監査、スパム対策の制御を弱めるものではありません。reader は常に変更を伴わないモードです。inbox では個人メッセージ、下書き、メディア、連絡先、プライバシー設定を利用できます。community-admin ではモデレーション、グループ／チャンネル、権限、ボットコマンドのワークフローを利用できます。research では範囲を限定したアカウント／公開情報の検索と閲覧を利用できます。

有効なプロファイルは /.well-known/mcp-server.json と _manifest に表示されます。各公開範囲の正確な用途については、TOOL_PROFILES.md を参照してください。

マルチアカウントの設定

ラベルごとに接尾辞付き環境変数を使用します。ラベルは小文字に正規化され、a-z、0-9、_、- のみを含める必要があります。プロファイル名、電話番号、トークンが公開されることはありません。

TELEGRAM_ACCOUNTS_WORK_API_ID=12345
TELEGRAM_ACCOUNTS_WORK_API_HASH_FILE=/run/secrets/work_api_hash
TELEGRAM_ACCOUNTS_WORK_PHONE_NUMBER=+15551234567

TELEGRAM_ACCOUNTS_PERSONAL_API_ID=12345
TELEGRAM_ACCOUNTS_PERSONAL_API_HASH_FILE=/run/secrets/personal_api_hash
TELEGRAM_ACCOUNTS_PERSONAL_PHONE_NUMBER=+15557654321

TELEGRAM_ACCOUNTS_WORK_PROXY_TYPE=mtproto
TELEGRAM_ACCOUNTS_WORK_PROXY_SERVER=proxy.example.net
TELEGRAM_ACCOUNTS_WORK_PROXY_PORT=443
TELEGRAM_ACCOUNTS_WORK_PROXY_SECRET_FILE=/run/secrets/work_mtproto_secret

明示的に上書きしない限り、各アカウントにはプラットフォームのアプリデータディレクトリ内に個別の TDLib データベースとダウンロードディレクトリが割り当てられます。マルチアカウントモードでは、すべての Telegram ツールで account 引数が必要です。このサーバーは、読み取りリクエストを意図的にすべてのアカウントに振り分けません。指定がない場合は、誤ったアカウントのデータを開示しないよう、フェイルクローズで失敗する必要があります。list_accounts を呼び出すと、認証済みの MCP クライアントから参照できるラベルを確認できます。

リモート MCP クライアントでは、クライアントごとにスコープを限定したキーを使用することを推奨します。

MCP_SECURITY_CLIENTS_0_ID=work-agent
MCP_SECURITY_CLIENTS_0_API_KEY_FILE=/run/secrets/work_mcp_key
MCP_SECURITY_CLIENTS_0_ALLOWED_ACCOUNTS_0=work

allowed-accounts リストが空の場合、設定済みのすべてのアカウントが許可されます。管理者キーに限って使用してください。従来の MCP_API_KEY は、単一アカウント構成と信頼されたローカル環境で引き続きサポートされます。

API キー認証

サーバーは、次の標準的なヘッダー形式を常にサポートします。

Authorization: Bearer <your-api-key>

または

X-MCP-API-Key: <your-api-key>

MCP_AUTH_HEADER に別のヘッダー名を設定すると、そのヘッダーも受け付けます。

mcp.security.clients で設定した場合、各認証済みキーには任意のアカウント許可リストが紐付けられ、ツールが TDLib にアクセスする前に適用されます。

認証が不要な公開エンドポイント：

GET /actuator/health
GET /actuator/info
GET /.well-known/mcp-server.json

well-known ディスクリプターは、意図的に小規模で安定したものになっています。汎用インストーラーやオーケストレーション層が、単一目的のコネクターを検出できるようにします。このサーバーをプロセス内アグリゲーターに変えるものではありません。

対話型の /auth/** エンドポイントで認証が不要なのは、ループバック経由の場合に限られます。Docker ブリッジ、リバースプロキシ、プライベート LAN からのリクエストには、設定済みの MCP API キーが必要です。プライベート IP アドレス空間は、信頼できる ID として扱われません。

CSRF 保護は、ループバック経由のリクエストを含め、状態を変更するリクエストに適用されます。検証済みの API キーヘッダー、OAuth Bearer トークン、認証ウィザードで検証済みの nonce ヘッダーのみが CSRF トークンの要件を回避できます。スクリプトから HTTP を使用する場合は、MCP API キーを設定し、localhost でも送信してください。有効な CSRF トークンを伴わないキーなしの POST（/auth/logout や /mcp を含む）は 403 を返します。ブラウザー認証ウィザードは nonce を自動的に処理します。

API キーモードでキーが設定されていない場合は、/mcp と保護対象の Actuator エンドポイントにも同じフェイルクローズのルールが適用されます。Raw HTTP はデフォルトで 127.0.0.1 にバインドされます。リモート環境で利用する場合は、SERVER_ADDRESS を明示的に変更し、API キーまたは OAuth を設定する必要があります。

オーケストレーションとツールのバインド

このリポジトリは MCP コネクター（ツールサーバー）であり、自律型エージェントの実行環境ではありません。

TDLib にアクセスできるだけでは、LLM が Telegram ツールを呼び出すことはありません。エンドツーエンドで動作させるには、外部の MCP ホスト、エージェントループ、またはオーケストレーションサービスが必要です。

この MCP サーバーからツールスキーマを取得します。
現在のターンで使用するツールスキーマをモデルに送信します。
モデルから要求されたツール呼び出しを、この MCP サーバーに対して実行します。
最終的なアシスタントの回答が生成されるまで、ツールの結果をモデルに返します。

このオーケストレーション層がない場合、プロンプトは通常のテキスト生成として処理され、Telegram の操作は実行されません。

複数のコネクターを使用するルーターを利用する場合は、チャットリクエストごとにコネクターの対象範囲を明示的に指定し、Telegram のターンでは Telegram ツールのみが公開されるようにしてください。

安全モデル

Telegram アカウントの認証情報と TDLib セッションデータは機密情報です。可能であればテストアカウントから始め、サービスを localhost にバインドし、長くランダムな MCP_API_KEY を使用して、書き込みが必要になるまでは MCP_READ_ONLY=true にしてください。読み取り専用モードでは、ローカル限定の download_media 例外を MCP_READ_ONLY_ALLOW_DOWNLOADS=true で明示的に有効にしない限り、書き込みツールとクォータを消費するツールは MCP ツール一覧に表示されません。多層防御として、実行時のガードも引き続き有効です。MCP_CONFIRMATION_REQUIRED=true にすると、破壊的な操作に呼び出し元の確認手順が追加されます。ただし、サーバーは "confirmed": true が人間によって設定されたことを証明できません。このフラグはツール呼び出し内で渡されるため、悪意あるメッセージに反応するモデルが自ら設定できます。

MCP_DESTRUCTIVE_APPROVAL=auto にすると、この問題を解消できます。破壊的なツールを実行する前に人間に確認を求め、モデルが書き込めない経路で回答を受け取ります。そのため、プロンプトインジェクションによる指示でモデルに禁止を要求させることはできても、承認させることはできません。この確認は、Telegram への呼び出しより前に行われます。

確認画面が表示される場所はクライアントによって異なります。MCP elicitation を実装しているホストでは、ホスト独自のプロンプトが表示されます。ほとんどのホストは実装していません。Claude Desktop は elicitation 機能を持たないと表明しているため、auto はこのサーバーが 127.0.0.1 でホストするページに切り替えます。リンクは、クライアントでサーバーの出力が表示される stderr に通知されます。これは安全性が低い方法ではありません。リンクは一度だけ使用でき、nonce で保護され、あなたのマシンからのみアクセスでき、期限が切れると拒否されます。フォールバックせずに失敗させたい場合は、elicitation または loopback を指定して経路を固定してください。大切なアカウントでは、この設定を有効にしてください。

ループバックページはサーバープロセスに属します。公開されていない Docker ネットワーク名前空間内では、127.0.0.1 はあなたのマシンではなくコンテナーを指すため、ホスト側のブラウザーから開くことはできません。そのため、telegram-mcp config --docker ... --writes は MCP_DESTRUCTIVE_APPROVAL=auto ではなく MCP_DESTRUCTIVE_APPROVAL=elicitation を生成します。elicitation を実装しているクライアントであれば引き続き確認を求めますが、実装していないクライアントでは、誰もアクセスできないページで待機するのではなく、破壊的なツールをそのまま拒否します。ループバック経路を使う場合は、サーバーをネイティブ環境で実行してください。

TELEGRAM_ALLOWED_CHAT_IDS が空の場合、コネクターは選択した Telegram アカウント全体を参照できます。リモート環境やモデルに公開する環境では、ワークフローの対象範囲がより狭い場合、明示的なチャットの許可リストを設定してください。この設定が制御するのは、チャット、メッセージ、フォルダーのデータと、チャットを対象とする副作用です。アカウント全体を完全に隔離するものではありません。アカウント、プロフィール、連絡先のメタデータを扱うツールは、引き続きアカウントスコープ、ツールプロファイル、MCP_TOOL_ALLOW／MCP_TOOL_DENY によって制御されるため、必要に応じてこれらの対象範囲も個別に絞ってください。

監査サマリーと JSONL レコードには、MCP_AUDIT_LOG_ARGS=true を指定しない限り引数の値は含まれません。有効にした場合、認識されている認証情報フィールドはマスキングされます。永続的なローカル記録を残すには、MCP_AUDIT_FILE を設定して強制 JSONL レコードを追記してください。ディレクトリは自動的に作成されます。シンボリックリンクの参照先は拒否され、POSIX ファイルへのアクセスは所有者のみに制限されます。記録は永続性のある暗号化ボリュームに保存し、通常のログ保持ポリシーとアクセス制御を適用してください。

サーバーは API ハッシュ、ボットトークン、2FA パスワード、認証コード、MCP API キーをディスクに書き込みません。これらは環境変数またはマウントした *_FILE シークレットを通じて渡してください。シークレットファイルは通常のファイルでなければならず（シンボリックリンク不可）、サイズに上限があり、グループやその他のユーザーによる書き込みが許可されていてはなりません。OS またはボリュームのレイヤーで TDLib セッションストレージを暗号化してください。Windows では BitLocker、macOS では FileVault、Linux では LUKS／fscrypt または暗号化ボリュームを使用してください。

ローカル状態の保存先には、既定で OS 標準のパスが使用されます。Windows では %LOCALAPPDATA%\\TelegramMcpServer、macOS では ~/Library/Application Support/TelegramMcpServer、Linux では $XDG_DATA_HOME/telegram-mcp-server（または ~/.local/share/telegram-mcp-server）です。相対パスで設定したパスは、現在の作業ディレクトリではなく、その保存先の下に解決されます。コンテナーイメージでは TELEGRAM_MCP_DATA_DIR=/data/tdlib-data が設定されており、これは Compose ボリュームによってバックアップされています。別のコンテナーオーケストレーターで複数アカウントのサーバーを実行する場合は、同じ変数に暗号化されたボリュームの絶対パスを設定してください。

ツールの応答には、他の Telegram ユーザーが書き込んだテキスト、リンク、ファイルが含まれる場合があります。MCP クライアントまたはエージェントでは、これらの内容を信頼できないデータとして扱い、クライアントの指示を上書きさせないでください。コネクターは返された Telegram の内容を指示として解釈しないため、プロンプトインジェクションポリシーは MCP ホストまたはエージェント側で定める必要があります。サーバーは引き続き入力サイズを制限し、オプションでオペレーターが定義する mcp.guardrails.blocked-patterns の拒否リストをサポートします。

transcribe_voice_note は Telegram 独自の Premium／試用版音声認識機能を使用します。新しい文字起こしメッセージを投稿したり、サードパーティーのサービスに音声をアップロードしたりすることはありませんが、Telegram の音声認識利用枠を消費する場合があるため、読み取り専用モードではブロックされ、レート制限の対象となります。

プライバシー設定、ボットコマンド、詳細なグループ権限への書き込みは、アカウントごとに適用され、監査されます。また、MCP_READ_ONLY=true の場合は利用できません。グループ全体、メンバー、管理者の権限変更は、MCP_CONFIRMATION_REQUIRED=true の場合、確認が必要です。グループ権限の更新では、呼び出し元が指定しないすべてのフラグが保持されます。一方、管理者権限の更新では、権限一式が意図的に置き換えられ、指定されなかった権限は取り消されます。

リモート環境にデプロイする場合は、サービスの前段で TLS を終端し、ネットワークアクセスを制限してください。デプロイモードとSECURITY.mdを参照してください。

利用可能な MCP ツール

コンパクトなタスクと永続的なエクスポート

ツール	説明
`inbox_snapshot`	JSON 文字数の予算内で取得する、未読受信トレイ
`conversation_bundle`	排他的な「指定日時より前」カーソルを使用する、コンパクトな会話ページ
`changes_since`	明示的な取得範囲の欠落情報を含む、永続化された監視済みメッセージの変更
`wait_for_changes`	再開可能なカーソルとオプションのチャットフィルターを使用して、監視済みメッセージの変更を待機
`export_job`	永続的な履歴エクスポートの開始、再開、確認、読み取り、キャンセル、削除

コンパクトなタスクとエクスポートおよび管理対象のローカルデーモンを参照してください。

すべてのツールは、共有の構造化エラー形式を含む型付き出力スキーマを提示します。

全ツールの一覧は以下にグループ化されています。実際には、すべてを一度に有効にするのではなく、ツールプロファイルから始めてください。

全 116 個のツールを表示

### メッセージ（30 個のツール）

ツール	説明
`get_history`	チャット履歴（最近のメッセージ）を取得します
`get_messages`	ID を指定してメッセージを取得します
`search_messages`	特定のチャット内のメッセージを検索します
`search_global`	すべてのチャットを横断してメッセージを検索します
`send_message`	HTML／Markdown に対応したテキストメッセージを送信します。任意で永続的な冪等性キーを指定できます。配信の復旧をご覧ください
`get_send_operation`	送信先と冪等性キーを指定して、アカウント単位の配信確認情報を読み取ります
`reply_to_message`	特定のメッセージに返信します
`edit_message`	既存のメッセージを編集します
`delete_message`	メッセージを削除します（取り消せない操作のため、確認が必要です）
`forward_message`	チャット間でメッセージを転送します
`pin_message`	チャット内のメッセージをピン留めします
`unpin_message`	メッセージのピン留めを解除します
`get_pinned_messages`	チャット内のピン留めされたメッセージをすべて取得します
`mark_as_read`	メッセージを既読にします
`send_reaction`	メッセージに絵文字リアクションを追加します（確認が必要です）
`remove_reaction`	メッセージから絵文字リアクションを削除します（確認が必要です）
`get_message_reactions`	リアクション数を取得し、Telegram が許可する場合は送信者の一覧も取得します
`create_poll`	投票を送信します（匿名または公開、単一回答または複数回答）
`vote_poll`	0 始まりの選択肢インデックスを指定して投票します
`close_poll`	投票を完全に終了します（取り消せない操作のため、確認が必要です）
`get_message_viewers`	少人数グループで、送信したメッセージの既読通知一覧を取得します
`get_message_context`	対象メッセージの前後にある N 件のメッセージを取得します
`list_inline_buttons`	メッセージ上のインラインキーボードボタンを確認します
`press_inline_button`	インデックスまたはラベルを指定してインラインボタンをクリックします（確認が必要です）
`message_from_link`	t.me のメッセージリンクから実際のメッセージを特定します
`get_message_link`	メッセージまたはメディアアルバムの共有可能な t.me リンクを作成します
`list_scheduled_messages`	チャットの送信待ちメッセージ一覧を取得します
`schedule_message`	ISO 形式の日時または Unix タイムスタンプを指定して、テキストメッセージを予約送信します
`reschedule_message`	予約済みメッセージの送信時刻を変更します
`cancel_scheduled_message`	予約済みメッセージをキャンセルします（取り消せない操作のため、確認が必要です）

チャット（45 個のツール）

ツール	説明
`list_chats`	オプションで種類や未読のフィルターを指定して、すべてのチャットを一覧表示します
`get_chat`	チャットの詳細情報（メンバー、説明）を取得します
`get_participants`	グループまたはチャンネルのメンバーを取得します
`create_group`	新しい基本グループを作成します
`create_supergroup`	フォーラム機能を有効にするかどうかを指定して、非公開のスーパーグループを作成します
`invite_to_group`	ユーザーをグループに招待します
`leave_chat`	チャットから退出します（破壊的な操作、確認が必要です）
`ban_user`	チャットからユーザーを禁止します（破壊的な操作です）
`unban_user`	ユーザーの禁止を解除します
`promote_admin`	ユーザーを管理者に昇格させます
`demote_admin`	管理者を一般メンバーに降格させます
`edit_chat_title`	チャットのタイトルを変更します
`set_chat_description`	グループ、スーパーグループ、またはチャンネルの説明を置き換えます
`set_slow_mode`	スーパーグループのスローモードの遅延時間を設定します（有効にする場合は確認モードが必要です）
`edit_chat_photo`	チャットの写真を設定または置き換えます（書き込み、ファイルセキュリティ）
`delete_chat_photo`	チャットの写真を削除します（破壊的な操作、確認が必要です）
`archive_chat`	チャットをアーカイブします
`unarchive_chat`	チャットのアーカイブを解除します
`mute_chat`	チャットの通知をミュートします
`unmute_chat`	チャットの通知のミュートを解除します
`list_topics`	スーパーグループのフォーラムトピックを一覧表示します
`create_topic`	トピック機能が有効なスーパーグループにフォーラムトピックを作成します
`edit_forum_topic`	フォーラムトピックの名前を変更し、必要に応じてカスタム絵文字アイコンを更新します
`close_forum_topic`	フォーラムトピックを閉じます
`reopen_forum_topic`	閉じたフォーラムトピックを再度開きます
`set_forum_topics_enabled`	スーパーグループのフォーラムトピックを有効または無効にします
`create_channel`	フォーラム機能を有効にするかどうかを指定して、新しいチャンネルまたはスーパーグループを作成します（破壊的な操作、確認が必要です）
`get_invite_link`	チャットの招待リンクを生成します
`list_invite_links`	現在のアカウントがチャット用に作成した招待リンクを一覧表示します
`revoke_invite_link`	招待リンクを無効にします（破壊的な操作、確認が必要です）
`join_chat_by_link`	招待リンクからチャットに参加します（破壊的な操作、確認が必要です）
`subscribe_public_channel`	ユーザー名で公開チャンネルを登録します（冪等です）
`get_admins`	チャットの管理者を一覧表示します
`get_banned_users`	チャットで禁止されているメンバーを一覧表示します
`search_public_chats`	Telegram の公開チャットのグローバルカタログを検索します
`get_recent_actions`	スーパーグループまたはチャンネルの管理者イベントログを取得します
`list_chat_folders`	TDLib が把握しているアカウントのチャットフォルダーを一覧表示します
`get_chat_folder`	1 つのフォルダーに一致する完全なルールを読み取ります
`configure_chat_folder`	フォルダー設定を作成するか、完全に置き換えます
`delete_chat_folder`	チャットから退出せずにフォルダーを削除します（破壊的な操作、確認が必要です）
`reorder_chat_folders`	指定された完全な ID シーケンスに従ってフォルダーを並べ替えます
`get_group_permissions`	グループのデフォルトの権限フラグを取得します
`set_group_permissions`	選択したグループのデフォルト権限フラグを更新します（有効にする場合は確認モードが必要です）
`set_member_permissions`	メンバーを禁止せずに、個別のメンバーを制限または元に戻します（有効にする場合は確認モードが必要です）
`set_admin_rights`	1 人のメンバーに対する管理者権限の詳細セットを置き換えます（有効にする場合は確認モードが必要です）

configure_chat_folder は、意図的に完全な TDLib フォルダー定義を送信します。 folder_id が指定されている場合、不明な状態を暗黙的にマージするのではなく、そのフォルダーのルールを置き換えます。list_chat_folders は、TDLib のアカウントフォルダー更新ストリームからデータを取得します。既知のフォルダー ID の完全なルールを取得するには、get_chat_folder を呼び出してください。スケジュールされたタイムスタンプには、未来の ISO-8601 時刻または Unix エポック秒を指定できます。繰り返しスケジュールには、Telegram によって製品やアカウントの制限が適用されます。

アカウントのプライバシーとボットコマンド（4 ツール）

ツール	説明
`get_privacy_settings`	1 つのアカウントプライバシー設定のルールをすべて取得します
`set_privacy_settings`	明示的なユーザー／チャットの例外を指定して、1 つのプライバシールールセットを置き換えます
`get_bot_commands`	言語と対象範囲を指定して、ボットコマンドメニューを取得します
`set_bot_commands`	ボットコマンドメニューを置き換えます。ユーザーアカウントでは Telegram に拒否されます

set_privacy_settings は、選択した設定のルールセット全体を意図的に置き換えます。基本となる対象範囲に加え、ユーザー、チャット、ボット、Premium ユーザーの例外を明示的に指定できます。TDLib のすべての設定をそのまま反映するものではありません。ボットコマンドツールは、Telegram のデフォルト、すべてのプライベートチャット、すべてのグループ、すべての管理者、チャット、チャット管理者、チャットメンバーの各スコープに対応しています。

ユーザーと連絡先（16 ツール）

ツール	説明
`get_me`	現在のユーザープロフィールを取得します
`list_contacts`	アドレス帳の連絡先一覧を取得します
`resolve_username`	@username を数値 ID に解決します
`add_contact`	ユーザーを連絡先に追加します
`delete_contact`	連絡先を削除します（破壊的操作）
`block_user`	ユーザーをブロックします（破壊的操作）
`unblock_user`	ユーザーのブロックを解除します
`update_profile`	名、姓、プロフィール文のいずれか、またはすべてを更新します
`set_profile_photo`	プロフィール写真をアップロードして設定します（書き込み、ファイルセキュリティ）
`delete_profile_photo`	現在のプロフィール写真を削除します（破壊的操作、確認が必要）
`get_user_photos`	ユーザーのプロフィール写真を取得します
`search_contacts`	ローカルの連絡先一覧を名前で検索します
`get_blocked_users`	ブロックしたユーザー／送信者の一覧を取得します
`get_user_status`	ユーザーのオンライン状態／最終ログイン時刻を取得します
`get_last_interaction`	連絡先と最後にやり取りしたメッセージを取得します
`get_common_chats`	ユーザーと共通のグループおよびチャンネルを一覧表示します

メディア（7 ツール）

ツール	説明
`get_media_info`	メッセージ内のメディアのメタデータを取得します
`download_media`	アカウントのキャッシュにメディアをダウンロードします（読み取り専用モードでは `MCP_READ_ONLY_ALLOW_DOWNLOADS=true` が必要です）
`send_file`	ファイルをアップロードして送信します
`send_voice`	チャットに音声メッセージ（OGG/Opus）を送信します（書き込み、ファイルセキュリティ）
`transcribe_voice_note`	音声メッセージの Telegram ネイティブ文字起こしをリクエストします（Premium／トライアルの利用枠が必要です。新しいメッセージは送信されません）
`send_sticker`	チャットにステッカー（WEBP/TGS/WEBM）を送信します（書き込み、ファイルセキュリティ）
`get_sticker_sets`	インストール済みの通常のステッカーセットを一覧表示します

下書き（3 ツール）

ツール	説明
`save_draft`	チャットにメッセージの下書きを保存します（返信として保存することもできます）
`get_drafts`	下書きが空でないすべてのチャットをまとめて取得します
`clear_draft`	チャットの下書きを消去します

公開検索（3 ツール）

ツール	説明
`discover_public_chats`	公開チャットを検索します。オペレーターの許可リストで絞り込むこともできます
`search_public_messages`	クライアントが指定した複数言語のクエリ候補を使って、複数のチャットを検索します
`export_chat_history`	ローカル分析用に、範囲を限定した履歴をエクスポートします

search_public_messages はロケールを推測したり、非公開の製品用語集を適用したりしません。翻訳、同義語、スラング、想定される誤字については、query_variants を指定してください。説明やピン留めされたメッセージの解釈は MCP ホストまたは製品オーケストレーターで行ってください。ロケール固有の宣伝やアウトリーチのポリシーを設定でき、Telegram の通信処理と切り離して運用できます。

メタ（3 ツール）

ツール	説明
`_manifest`	実行中のリリースを `serverVersion` に含む、簡潔な自己紹介とグループ別ツール一覧を返します
`list_accounts`	認証済み MCP クライアントから参照できるアカウントのルーティングラベルを一覧表示します
`register_internal_chat`	オペレーターの管理用チャットを内部のスパム対策コンテキストとして登録します（破壊的操作、確認が必要。このチャットのレート制限が緩和されます）

## 新しいツールの追加方法

src/main/kotlin/dev/telegrammcp/server/tool/ に新しいクラスを作成します。

@Component
class MyNewTool(
    private val telegramService: TelegramClientService,
    private val guardrailService: GuardrailService,
    private val objectMapper: ObjectMapper,
    private val meterRegistry: MeterRegistry,

) : McpToolHandler {

    override fun definition(): McpSchema.Tool = ToolSupport.definition(
        "my_new_tool",
        "Description of what this tool does",
        INPUT_SCHEMA,
        objectMapper,
    )

    override fun execute(
        exchange: McpSyncServerExchange,
        arguments: Map<String, Any>,
    ): McpSchema.CallToolResult {
        // Your logic here
    }
}

これだけです。ツールは起動時に自動検出され、登録されます。McpConfig は、アカウントに紐づくツールに安全な account セレクターを自動的に追加します。

プロジェクト構成

src/main/kotlin/dev/telegrammcp/server/
├── TelegramMcpApplication.kt          # Entry point
├── api/                                # Loopback-only interactive auth wizard endpoints
├── auth/                               # TDLib auth orchestration & runtime credentials
├── cli/                                # serve / auth / session / version commands
├── client/                             # Telegram client abstraction
│   ├── TelegramClientService.kt        # Telegram capability interface
│   ├── TdLibClientService.kt           # TDLib implementation
│   ├── TdLibConfig.kt                  # TDLib bean configuration & lifecycle
│   ├── TelegramAccountRegistry.kt      # Isolated multi-account routing
│   └── FallbackClientConfig.kt         # Fallback when TDLib unavailable
├── config/                             # Typed configuration properties & MCP wiring
│   ├── TdLibProperties.kt              # TDLib config (api, auth, database, session, proxy)
│   ├── McpSecurityProperties.kt
│   ├── ServerModeProperties.kt
│   └── McpConfig.kt                    # Tool registration, profiles, account selector
├── controller/                         # Well-known descriptor & OAuth metadata endpoints
├── model/                              # Domain models
│   ├── TelegramModels.kt
│   ├── EntityIdentifier.kt             # Sealed hierarchy: NumericId / Username / PhoneNumber
│   └── UserInfo.kt                     # UserInfo + ContactInfo
├── security/                           # Spring Security, API keys, account scoping
│   ├── SecurityConfig.kt
│   ├── ApiKeyAuthFilter.kt
│   ├── AccountAccessPolicy.kt
│   └── SecretResolver.kt               # *_FILE mounted-secret validation
├── service/                            # Business logic
│   ├── EntityResolverService.kt        # @username / +phone / ID resolution
│   ├── GuardrailService.kt             # Input limits & chat access
│   ├── OperationGuardService.kt        # Read-only & confirmation modes
│   ├── ToolSurfacePolicy.kt            # Tool profiles & allow/deny filters
│   ├── AntiSpamGuardService.kt         # Rate limits, daily caps, dedup
│   ├── AuditService.kt                 # Audit logging
│   └── FileSecurityService.kt          # File upload security
├── tool/                               # MCP Tools (auto-discovered)
│   ├── McpToolHandler.kt               # Tool interface
│   ├── message/                        # 30 message tools
│   ├── chat/                           # 49 chat, folder, permission & privacy tools
│   ├── user/                           # 16 user/contact tools
│   ├── media/                          # 7 media tools
│   ├── draft/                          # 3 draft tools
│   ├── research/                       # 3 bounded public-search tools
│   └── meta/                           # 3 manifest/account tools
├── util/                               # StructuredLogger, TextFormatter, MdcFilter
└── exception/                          # McpExceptions, GlobalExceptionHandler

テスト

# Unit tests
./gradlew test

# Specific test class
./gradlew test --tests "dev.telegrammcp.server.service.GuardrailServiceTest"

コントリビューションとサポート

プルリクエストを作成する前に CONTRIBUTING.md を読み、リリース履歴については CHANGELOG.md をご確認ください。脆弱性については、公開イシューを作成せず、SECURITY.md に従ってください。コミュニティの行動規範は CODE_OF_CONDUCT.md に記載されています。

メトリクス

Prometheus が有効な場合、メトリクスは /actuator/prometheus で利用できます。

mcp.tool.execution — ツール名ごとのツール実行時間
mcp.audit.operations — ツール、カテゴリ、結果ごとの監査カウンター
telegram.api.rate_limited — レートリミッターによる拒否
telegram.api.circuit_open — サーキットブレーカーのオープンイベント
標準の Spring Boot／Micrometer HTTP メトリクス

ライセンス

Apache License 2.0

Markdown 対応

ログインしてコメント

基本情報

作者: tolboy
バージョン: 1.18.0
トランスポート: stdio
掲載日: 2026年10月26日
最終更新: 2 日前
公式 Registry: io.github.tolboy/telegram-mcp-tdlib

問題を報告

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。

Telegram MCP Server

Telegram MCP Server について

主な機能

活用シーン

MCP 対応

設定

ツール

詳細

Telegram MCP サーバー

このサーバーの特長

安全な初回起動

クライアントを接続する

レシピ

比較

ツールプロファイル

機能

クイックスタート

前提条件

1. クローンして設定する

2. ローカルで実行する

最初の 60 秒

3. Docker で実行する

リリース

環境変数

TDLib（主要な Telegram クライアント）

Telegram プロキシ

サーバーとセキュリティ

ツールプロファイル

マルチアカウントの設定

API キー認証

オーケストレーションとツールのバインド

安全モデル

利用可能な MCP ツール

コンパクトなタスクと永続的なエクスポート

チャット（45 個のツール）

アカウントのプライバシーとボットコマンド（4 ツール）

ユーザーと連絡先（16 ツール）

メディア（7 ツール）

下書き（3 ツール）

公開検索（3 ツール）

メタ（3 ツール）

プロジェクト構成

テスト

コントリビューションとサポート

メトリクス

ライセンス

コメント

MCP は初めてですか？

MCP（Model Context Protocol）とは？

MCP サーバーとクライアントの違いは？

ローカルとリモート、どちらを選ぶべき？

Claude や Cursor にサーバーを導入するには？

掲載プロジェクトは審査されていますか？「認証済み」とは？

自分のプロジェクトが掲載されています。どう申請できますか？