mcp-telegram

ClaudeのようなAIアシスタントを、User API (MTProto) を介してあなたの実際のTelegramアカウントに接続する MCP サーバーです。ボットではなく、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 との比較

• クイックスタート

• クライアント設定

• 設定リファレンス

• セキュリティ

機能

その他の機能:

• ファイルおよび写真の送信

• チャット間でのメッセージ転送

• 特定のメッセージへの返信

• メッセージ履歴からの写真やドキュメントのダウンロード

• 日付範囲による履歴フィルタリング (since / until)

• 型付きピア参照 (user:ID, chat:ID, channel:ID) によるID衝突の防止

• 遅延ピア解決 — 起動時の FLOOD_WAIT エラーを回避

• RPCレベルでのグローバルレート制限

できること

接続が完了すると、AIアシスタントに以下のような指示を出せます：

メッセージの確認

• 「Telegramの未読メッセージを確認して要約して」

• 「@alice が過去24時間に書いた内容は？」

• 「月曜日以降のDev Teamチャットのメッセージを見せて」

返信とコミュニケーション

• 「@bob からの最後のメッセージへの返信を下書きして（まだ送信しないで）」

• 「@alice に『了解、午後3時に会いましょう』と送って」

• 「プロジェクトチャットのメッセージ1234にフィードバックを返信して」

受信トレイの管理

• 「ニュースチャンネルのメッセージをすべて既読にして」

• 「ホワイトリストに登録されているチャットのうち、未読があるものはどれ？」

• 「デザインチャットの今日のメッセージから写真をダウンロードして」

調査と分析

• 「先週のデプロイメントについて言及しているメッセージをすべて見つけて」

• 「昨日のチームチャットでの議論を要約して」

• 「今月プロジェクトチャンネルで共有されたファイルは何？」

chaindead/telegram-mcp との比較

クイックスタート

前提条件

• Go 1.26+

• Telegramアカウント

• my.telegram.org から取得したAPI認証情報 (api_id および api_hash)

インストール

Homebrew (macOS / Linux):

brew install Prgebish/tap/mcp-telegram

ビルド済みバイナリ (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）が生成されます。

認証

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

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 (設定 > MCPサーバー > 追加):

{
  "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 に明示的にリストされたチャットのみがアクセス可能であり、指定した権限のみが許可されます。

サポートされているマッチパターン:

権限タイプ: 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

このプロジェクトが役に立った場合は、ぜひスターを付けてください。他の人の発見につながります。