telegram-mcp

mtcuteを使用してTelegramと対話するためのModel Context Protocol (MCP) サーバーです。

機能

• チャットへのテキストメッセージ送信

• 特定のチャットでの受信メッセージ待機

• チャットからのメッセージ読み取り

• メッセージ検索

• ダイアログ（チャット）の一覧表示および情報取得

• すべてのチャットにわたる最近のメッセージの取得

• アカウントおよびチャンネルの絵文字ステータスIDの設定と確認

Related MCP server: io.github.daedalus/mcp-telegram-bot

セットアップ

インストール

オプション1: ビルド済みバイナリのダウンロード

リリースページから、お使いのプラットフォーム向けの最新リリースをダウンロードしてください：

• macOS (Apple Silicon): telegram-mcp-darwin-arm64.tar.gz

• macOS (Intel): telegram-mcp-darwin-x64.tar.gz

• Linux: telegram-mcp-linux-x64.tar.gz

• Windows: telegram-mcp-win-x64.exe.zip

アーカイブを解凍し、バイナリを実行可能にします（Unixシステムの場合）：

tar -xzf telegram-mcp-*.tar.gz
chmod +x telegram-mcp

オプション2: ソースからのビルド

1. リポジトリをクローンし、依存関係をインストールします：

git clone git@github.com:zhigang1992/telegram-mcp.git
cd telegram-mcp
bun install

2. 実行ファイルをビルドします：

bun run build

初期設定（初回のみ）

1. https://my.telegram.org からTelegram API認証情報を取得します。

2. 初期設定を実行してTelegramで認証します：

export API_ID=your_api_id
export API_HASH=your_api_hash
./telegram-mcp

サーバーは以下の動作を行います：

• 電話番号の入力を求めます

• Telegram経由で認証コードを送信します

• 認証コードの入力を求めます

• 絶対ストレージパスを表示します（MCP設定で必要になります）

3. 出力に表示されたストレージパスを控えておいてください。以下のような形式になります：

Storage path: /Users/username/telegram-mcp/bot-data/session

使用方法

MCPサーバーとして

初期設定で取得したストレージパスを使用して、Claude Desktopの設定に追加します：

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/telegram-mcp",
      "env": {
        "API_ID": "your_api_id",
        "API_HASH": "your_api_hash",
        "TELEGRAM_STORAGE_PATH": "/absolute/path/from/initial/setup"
      }
    }
  }
}

重要: TELEGRAM_STORAGE_PATH は、初期設定時に表示された絶対パスである必要があります。これにより、MCPサーバーが認証済みセッションを使用できるようになります。

利用可能なツール

メッセージツール

• messages_sendText - チャットにテキストメッセージを送信する

  • chatId (必須): チャット/ユーザーIDまたはユーザー名

  • text (必須): 送信するメッセージテキスト

  • replyToMessageId: 返信先のメッセージID（オプション）

• messages_getHistory - チャットからメッセージ履歴を取得する

  • chatId (必須): チャット/ユーザーIDまたはユーザー名

  • limit: メッセージ数（デフォルト: 100, 最大: 100）

  • offsetId: ページネーション用のメッセージID

• messages_search - メッセージを検索する

  • query (必須): 検索クエリ

  • chatId: 検索対象の特定のチャット（オプション）

  • limit: 結果の数（デフォルト: 50）

• messages_getRecent - すべてのチャットから最近のメッセージを取得する

  • limit: チャット数（デフォルト: 10）

  • messagesPerChat: チャットごとのメッセージ数（デフォルト: 10）

インタラクティブツール

• wait_for_reply - チャット内の次のメッセージを待機する

  • chatId (必須): メッセージを待機するチャット/ユーザーIDまたはユーザー名

  • timeoutSeconds: タイムアウト（秒）（デフォルト: 60, 最大: 300）

ステータスツール

• status_getCurrent - ピアの現在の絵文字ステータスを取得する

  • peerId: 対象のピア、デフォルトは self

• status_setEmoji - 絵文字ステータスを設定またはクリアする

  • peerId: 対象のピア、デフォルトは self

  • emojiId: カスタム絵文字ドキュメントID（clear=trueでない限り必須）

  • isCollectible: emojiId が収集可能IDである場合に true に設定

  • until: ISO-8601タイムスタンプまたはUnixタイムスタンプ文字列（オプション）

  • clear: ステータスを設定する代わりに現在のステータスをクリアする

• status_listAvailable - 利用可能なデフォルトの絵文字ステータスIDを一覧表示する

  • scope: self または channel（デフォルト: self）

  • limit: 返すIDの最大数（デフォルト: 100）

• status_listCollectibles - 自己絵文字ステータスとして使用可能な所有中の収集可能IDを一覧表示する

  • owner: 確認するピア、デフォルトは self

  • limit: 返す収集可能アイテムの最大数（デフォルト: 100）

ダイアログツール

• dialogs_list - すべてのダイアログを一覧表示する

  • limit: ダイアログの最大数（デフォルト: 50）

  • filter: フィルタオプション（onlyUsers, onlyGroups, onlyChannels）

• dialogs_getInfo - 詳細なダイアログ情報を取得する

  • chatId (必須): チャット/ユーザーIDまたはユーザー名

開発

開発モードで実行：

bun run dev

サーバーはセッションデータを bot-data/ ディレクトリに保存します。