Mcp Telegram

mcp-telegram

ＭＣＰ サーバーです。User API（MTProto）を介して、Claude のような AI アシスタントを実際の Telegram アカウントに接続します。ボットではなく、Claude があなたになり代わってメッセージを読み、送信します。

gotd/td と公式の MCP Go SDK を使用して構築されています。

Telegram API 利用規約：このプロジェクトは Telegram User API を使用します。my.telegram.org から独自の api_id と api_hash を取得し、Telegram API 利用規約を遵守する必要があります。User API の不正使用（スパム、一斉メッセージ送信、スクレイピング）により、アカウントが停止される場合があります。このツールの使用方法については、すべてご自身の責任となります。

目次

• 機能
• できること
• chaindead/telegram-mcp との比較
• クイックスタート
• クライアントの設定
• 設定リファレンス
• セキュリティ

---

機能

ツール	機能	必要な権限
tg_me	現在のアカウント情報を返します	—
tg_dialogs	ACL 許可リストから参照できるダイアログを一覧表示します	—
tg_history	ページネーション、日付フィルター、メディアのダウンロードに対応してメッセージ履歴を取得します	read
tg_search	送信者の任意フィルターを指定して、テキストクエリでチャット内のメッセージを検索します	read
tg_send	テキストメッセージまたはファイルを送信します。返信先の指定も可能です	send
tg_forward	あるチャットから別のチャットへメッセージを転送します	read + send
tg_draft	下書きメッセージを保存します（送信はしません）	draft
tg_mark_read	チャットを既読にします	mark_read

その他の機能：

• ファイルと写真の送信
• チャット間でのメッセージ転送
• 特定のメッセージへの返信
• メッセージ履歴からの写真やドキュメントのダウンロード
• 日付範囲（since / until）による履歴のフィルター
• ID の衝突を防ぐ型付きピア参照（user:ID、chat:ID、channel:ID）
• 遅延ピア解決 — 起動時の FLOOD_WAIT エラーを回避します
• RPC レベルでのグローバルなレート制限

できること

接続すると、AI アシスタントに次のようなことを依頼できます。

メッセージを確認する

• 「Telegram の未読メッセージを確認して、要約して」
• 「過去 24 時間に @alice が書いた内容は？」
• 「月曜日以降の Dev Team チャットのメッセージを見せて」

返信してやり取りする

• 「@bob からの最新メッセージへの返信を下書きして。まだ送信しないで」
• 「@alice に『いいね、午後 3 時に会おう』と送って」
• 「プロジェクトチャットのメッセージ 1234 に、フィードバックを返信して」

受信トレイを管理する

• 「ニュースチャンネルをすべて既読にして」
• 「許可リストにあるチャットのうち、未読メッセージがあるのはどれ？」
• 「デザインチャットの今日のメッセージから写真をダウンロードして」

調査と分析を行う

• 「過去 1 週間の、デプロイに言及しているメッセージをすべて探して」
• 「昨日のチームチャットでの話し合いを要約して」
• 「今月、プロジェクトチャンネルで共有されたファイルは？」

---

chaindead/telegram-mcp との比較

	mcp-telegram	chaindead/telegram-mcp
アクセス制御	チャットごとに細かく権限を設定できる、デフォルト拒否の ACL ホワイトリスト	すべてのチャットにフルアクセス
ピアの指定	型付き参照（user:ID、chat:ID、channel:ID）	数値 ID のみ（衝突しやすい）
設定	環境変数を展開できる YAML 設定	CLI フラグ
起動時の安全性	ピアを遅延解決（API の一括呼び出しなし）	即時解決（FLOOD_WAIT のリスクあり）
レート制限	トークンバケットミドルウェアを標準搭載	なし
ファイルのサポート	ファイルや写真の送信、履歴からのメディアのダウンロード	テキストのみ
返信のサポート	あり	なし
日付による絞り込み	あり	なし

---

クイックスタート

前提条件

• Go 1.26+
• Telegram アカウント
• my.telegram.org の API 認証情報（api_id と api_hash）

インストール

Homebrew（macOS / Linux）：

brew install Prgebish/tap/mcp-telegram

NPX（インストール不要）：

npx @prgebish/mcp-telegram serve --config config.yaml

ビルド済みバイナリ（macOS / Linux / Windows）：

GitHub Releases からダウンロードしてください。

Go install：

go install github.com/Prgebish/mcp-telegram/cmd/mcp-telegram@latest

ソースからビルド：

git clone https://github.com/Prgebish/mcp-telegram.git
cd mcp-telegram
go build ./cmd/mcp-telegram

これにより、現在のディレクトリに mcp-telegram（Windows では mcp-telegram.exe）が生成されます。

認証

認証コマンドを一度実行して、セッションファイルを作成します。電話番号、ログインコード、および（有効な場合は）2FA パスワードの入力を求められます。

macOS / Linux：

export TG_APP_ID=12345
export TG_API_HASH="your_api_hash"

mcp-telegram auth --config config.yaml

Windows（PowerShell）：

$env:TG_APP_ID = "12345"
$env:TG_API_HASH = "your_api_hash"

mcp-telegram.exe auth --config config.yaml

Windows（cmd）：

set TG_APP_ID=12345
set TG_API_HASH=your_api_hash

mcp-telegram.exe auth --config config.yaml

設定

config.yaml を作成します。

telegram:
  app_id: ${TG_APP_ID}
  api_hash: ${TG_API_HASH}
  session_path: ~/.config/mcp-telegram/session.json

acl:
  chats:
    - match: "@username"
      permissions: [read, draft, mark_read]
    - match: "user:123456789"
      permissions: [read, send]
    - match: "channel:2225853048"
      permissions: [read, mark_read]

limits:
  max_messages_per_request: 50
  max_dialogs_per_request: 100
  rate:
    requests_per_second: 2.0
    burst: 3

logging:
  level: info

${...} 形式の環境変数は、読み込み時に展開されます。

クライアントの設定

サーバーは stdio 経由で通信します。MCP クライアントがプロセスを起動し、管理します。

Claude Code（CLI — コマンドで追加）：

claude mcp add telegram -- /path/to/mcp-telegram serve --config /path/to/config.yaml

Claude Desktop / Claude Code（~/.claude.json または claude_desktop_config.json）：

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/mcp-telegram",
      "args": ["serve", "--config", "/path/to/config.yaml"],
      "env": {
        "TG_APP_ID": "12345",
        "TG_API_HASH": "your_api_hash"
      }
    }
  }
}

Cursor（Settings > MCP Servers > Add）：

{
  "telegram": {
    "command": "/path/to/mcp-telegram",
    "args": ["serve", "--config", "/path/to/config.yaml"],
    "env": {
      "TG_APP_ID": "12345",
      "TG_API_HASH": "your_api_hash"
    }
  }
}

---

設定

ACL

ACL はデフォルト拒否です。acl.chats に明示的に記載されたチャットのみアクセスでき、指定した権限のみが付与されます。

サポートされる一致パターン：

パターン	例	説明
@username	@johndoe	Telegram のユーザー名で照合（大文字と小文字を区別しない）
+phone	+79001234567	電話番号で照合
user:ID	user:123456789	数値 ID でユーザーを照合
chat:ID	chat:987654321	数値 ID でグループチャットを照合
channel:ID	channel:2225853048	数値 ID でチャンネルまたはスーパーグループを照合

権限の種類：read、send、draft、mark_read。

同じピアが複数のルールに一致する場合（例：@username と user:ID の両方で一致する場合）、権限は統合され、互いに上書きされることはありません。

レート制限

limits.rate セクションでは、すべての Telegram RPC 呼び出しに適用されるグローバルトークンバケットを設定します。

• requests_per_second — 継続的なリクエストレート（デフォルト：2.0）
• burst — 最大バーストサイズ（デフォルト：3）

メディアのダウンロード

media:
  download: [photo, document, video, voice, audio]
  directory: ~/telegram-media
  allowed_upload_dirs:
    - ~/Documents
    - ~/Downloads

設定すると、tg_history はメディアファイルを指定したディレクトリに自動的にダウンロードします。download_to パラメーターでパスを変更できますが、指定できるのは media.directory またはそのサブディレクトリのみです。

allowed_upload_dirs は、tg_send がファイルを読み取れるディレクトリを制限します。これを設定しない限り、ファイル送信は無効です。

---

セキュリティ

• デフォルト拒否の ACL — 明示的にホワイトリストへ追加されない限り、どのチャットにもアクセスできません
• ファイルシステムの境界 — tg_send は allowed_upload_dirs 内のファイルのみ読み取れます。download_to は media.directory のサブディレクトリに制限されます
• セッションファイルの権限 — 0600（所有者のみ読み書き可能）に強制されます
• 秘密情報をログに記録しない — API ハッシュ、セッショントークン、認証キーがログに書き込まれることはありません
• アクセスハッシュを公開しない — 内部の Telegram アクセスハッシュは、すべてのツール出力から除去されます
• レート制限 — 意図しない API の過剰利用を防止します
• ローカルのタイムゾーン — 日付フィルターには UTC ではなく、システムのタイムゾーンが使用されます

---

ライセンス

MIT

---

このプロジェクトが役に立ったら、ぜひスターを付けてください。ほかの人にも見つけてもらいやすくなります。