🧠 Telegram Bot MCP Server

🧠 Telegram Bot MCP Server

インテリジェントなメッセージ分割、包括的なエラー処理、NPX サポートを備え、Telegram Bot API とシームレスに連携できる強力な Model Context Protocol（MCP）サーバーです。

✨ 主な機能

• 📝 45 種類のツール、幅広い API 対応範囲：メッセージ、メディア、アンケート、チャット管理、招待リンク、ボット設定
• 🔄 インテリジェントなメッセージ分割：単語の区切りと書式を保持しながら、Telegram の 4096 文字制限に自動で対応します
• 🖼️ メディアを全面サポート：file_id または URL による写真、ドキュメント、動画、音声、ボイスメッセージ、アニメーション、ステッカー
• 🎲 インタラクティブなコンテンツ：アンケート、クイズ、サイコロ、位置情報、連絡先、チャットアクション（入力中インジケーター）
• ✏️ メッセージのライフサイクル管理：メッセージの編集、削除、転送、コピー、ピン留め
• 👮 グループ管理：禁止／禁止解除、制限／ミュート、管理者への昇格、招待リンクの管理
• 🛡️ 包括的なエラー処理：コンテキスト、エラーコード、デバッグ情報を含む詳細なエラー報告
• 📦 NPX サポート：npx telegram-bot-mcp-server で直接実行できます。インストールは不要です
• 🔧 簡単な連携：AI アシスタント向けのシンプルな MCP クライアント設定

🚀 クイックスタート

オプション 1：NPX（推奨）

# Run directly without installation
npx telegram-bot-mcp-server

オプション 2：NPM でインストール

# Install globally
npm install -g telegram-bot-mcp-server

# Or install locally
npm install telegram-bot-mcp-server

📋 前提条件

1. Node.js 18 以降：こちらからダウンロード
2. Telegram ボットトークン：@BotFather から取得してください

ボットトークンの取得方法

1. Telegram を開き、@BotFather を検索します
2. 会話を開始し、/newbot を実行します
3. 表示される指示に従って、ボットに名前を付けます
4. 発行された API トークンをコピーします

🔧 MCP クライアントの設定

この設定を MCP クライアント（Claude Desktop など）に追加します。

{
  "mcpServers": {
    "telegram_bot": {
      "command": "npx",
      "args": ["telegram-bot-mcp-server"],
      "env": {
        "TELEGRAM_BOT_API_TOKEN": "your_bot_token_here"
      }
    }
  }
}

その他の設定方法

グローバルインストールを使用する場合：

{
  "mcpServers": {
    "telegram_bot": {
      "command": "telegram-bot-mcp-server",
      "env": {
        "TELEGRAM_BOT_API_TOKEN": "your_bot_token_here"
      }
    }
  }
}

ローカルインストールを使用する場合：

{
  "mcpServers": {
    "telegram_bot": {
      "command": "node",
      "args": ["./node_modules/.bin/telegram-bot-mcp-server"],
      "env": {
        "TELEGRAM_BOT_API_TOKEN": "your_bot_token_here"
      }
    }
  }
}

🛠️ 利用可能なツール（45 種類）

📨 メッセージ

ツール	説明	入力
send-message	テキストメッセージを送信します。4096 文字を超えるメッセージは、単語の区切りを保持しながら自動的に分割されます	chatId、text
edit-message-text	ボットが以前に送信したメッセージのテキストを編集します	chatId、messageId、text
delete-message	チャットからメッセージを削除します	chatId、messageId
forward-message	あるチャットから別のチャットにメッセージを転送します（元のメッセージへのリンクを保持します）	chatId、fromChatId、messageId
copy-message	元のメッセージへのリンクを付けずに、別のチャットにメッセージをコピーします	chatId、fromChatId、messageId
send-chat-action	「入力中…」や「写真を送信中…」などのステータスインジケーターを表示します	chatId、action

🖼️ メディア

ツール	説明	入力
send-photo	オプションのキャプションとともに写真を送信します（長いキャプションは自動的に分割されます）	chatId、media、text?
send-document	ドキュメント／ファイル（PDF、ZIP など、最大 50 MB）を送信します	chatId、media、caption?
send-video	MPEG4 動画を送信します	chatId、media、caption?
send-audio	音楽プレーヤー用の音声ファイル（.MP3/.M4A）を送信します	chatId、media、caption?
send-voice	再生可能なボイスメッセージ（.OGG/OPUS、.MP3、.M4A）を送信します	chatId、media、caption?
send-animation	アニメーション（GIF または音声なしの MPEG4）を送信します	chatId、media、caption?
send-sticker	静止画、アニメーション、または動画のステッカーを送信します	chatId、media
get-file	任意の file_id のファイル情報と、直接ダウンロードできる HTTPS リンクを取得します	fileId

すべてのメディアツールで、media には Telegram の file_id（推奨）または HTTP URL を指定できます。

🎲 インタラクティブコンテンツ

ツール	説明	入力
send-poll	ネイティブの投票またはクイズを送信します（匿名モード、複数回答、正解付きのクイズモード）	chatId、question、options、isAnonymous?、allowsMultipleAnswers?、type?、correctOptionId?
send-dice	アニメーション付きのランダム値絵文字（🎲 🎯 🏀 ⚽ 🎳 🎰）を送信します	chatId、emoji?
send-location	地図上の位置を送信します	chatId、latitude、longitude
send-contact	電話連絡先を送信します	chatId、phoneNumber、firstName、lastName?

👥 チャットとメンバーの管理

ツール	説明	入力
get-chat	チャットのメタデータと詳細情報をすべて取得します	chatId
get-chat-member	チャットメンバーの詳細情報を取得します	chatId、userId
get-chat-member-count	チャットのメンバー総数を取得します	chatId
get-chat-administrators	チャットのすべての管理者とその権限を一覧表示します	chatId
kick-chat-member	グループ、スーパーグループ、またはチャンネルからユーザーを追放します	chatId、userId
un-ban-chat-member	以前に追放したユーザーの追放を解除します	chatId、userId
restrict-chat-member	スーパーグループでユーザーをミュートするか、送信できる内容を制限します	chatId、userId、権限フラグ、untilDate?
promote-chat-member	ユーザーを管理者に昇格（または降格）させます	chatId、userId、管理者権限フラグ
get-user-profile-photos	ユーザーのプロフィール写真を取得します	userId、offset?、limit?
leave-chat	ボットをグループ、スーパーグループ、またはチャンネルから退出させます	chatId

🔧 チャット設定

ツール	説明	入力
set-chat-title	グループまたはチャンネルのタイトルを変更します	chatId、title
set-chat-description	グループまたはチャンネルの説明を変更します	chatId、description
pin-chat-message	メッセージをピン留めします（通知をオフにすることもできます）	chatId、messageId、disableNotification?
unpin-chat-message	メッセージ（または最新のピン留めメッセージ）のピン留めを解除します	chatId、messageId?
unpin-all-chat-messages	ピン留めされたメッセージのピン留めを一括解除します	chatId

🔗 招待リンク

ツール	説明	入力
create-chat-invite-link	追加の招待リンクを作成します（名前、有効期限、メンバー数上限を任意で設定できます）	chatId、name?、expireDate?、memberLimit?
revoke-chat-invite-link	ボットが作成した招待リンクを無効にします	chatId、inviteLink
export-chat-invite-link	新しいメインの招待リンクを生成します（古いリンクは無効になります）	chatId

🤖 ボットの設定

ツール	説明	入力
get-me	ボットの認証トークンをテストし、ボットの情報を取得します	—
set-my-name / get-my-name	ボットの名前を設定・取得します	name（0～64文字）
set-my-description / get-my-description	ボットの説明を設定・取得します（チャットが空の場合に表示されます）	description（0～512文字）
set-my-short-description / get-my-short-description	ボットの短い説明を設定・取得します（プロフィールページに表示されます）	short_description（0～120文字）
set-my-commands / get-my-commands	ボットのコマンドメニューを設定・取得します	{ command, description } の配列である commands

🆕 新機能

リッチメディアのサポート

• ドキュメント、動画、音声、ボイスメッセージ、アニメーション、ステッカー：file_id または URL であらゆる種類のメディアを送信します
• ファイルのダウンロード：get-file で任意の file_id を直接ダウンロードできる HTTPS リンクに解決します

インタラクティブコンテンツ

• 投票とクイズ：匿名モード、複数回答、正解付きのクイズモードに対応したネイティブの投票
• サイコロ、位置情報、連絡先：楽しいアニメーション絵文字、地図上の位置、電話連絡先
• チャットアクション：応答を準備している間、「入力中…」などのステータスインジケーターを表示します

メッセージのライフサイクル全般

• 編集と削除：ボットが送信したメッセージを編集または削除します
• 転送とコピー：帰属情報の有無を指定して、チャット間でコンテンツを移動します
• ピン留めの管理：メッセージをピン留め、ピン留め解除、一括ピン留め解除します

グループの管理

• モデレーション：メンバーの禁止、禁止解除、ミュート／制限、昇格を行います
• チャット設定：タイトルと説明を更新し、管理者の一覧を表示します
• 招待リンク：有効期限とメンバー数の上限を設定して、招待リンクを作成、無効化、再生成します

メッセージのインテリジェントな分割

• 自動検出：メッセージが4096文字を超えた場合に検出します
• スマート分割：単語の区切りと書式を維持します
• 順次配信：各パートの表示を付けて、順番に送信します
• 写真のキャプション：長い写真のキャプションを複数のメッセージに分割して処理します

エラー処理の強化

• 詳細なエラー：エラーコード、説明、コンテキストが含まれます
• Telegram API エラー：Telegram 固有のエラーを取得して整形します
• ネットワークの問題：接続エラーやタイムアウトエラーを処理します
• デバッグ情報：トラブルシューティングに役立つ包括的なログを記録します

NPX のサポート

• インストール不要：npx telegram-bot-mcp-server で直接実行できます
• CLI インターフェース：ヘルプとバージョンを表示するコマンドが組み込まれています
• 環境変数の検証：必須のボットトークンを確認します
• クロスプラットフォーム：Windows、macOS、Linux で動作します

🔍 トラブルシューティング

よくある問題

「No bot token」エラー

❌ Error: Missing Telegram Bot Token

解決方法：TELEGRAM_BOT_API_TOKEN 環境変数を設定します：

export TELEGRAM_BOT_API_TOKEN="your_token_here"
npx telegram-bot-mcp-server

「Something went wrong」エラー（旧形式）

詳細なエラーメッセージに置き換えられました。より適切なエラー報告を利用するには、最新バージョンに更新してください。

NPX コマンドが見つからない

解決方法：Node.js 18 以降がインストールされていることを確認します：

node --version  # Should be 18.0.0 or higher
npm --version   # Should be included with Node.js

権限エラー

解決方法：Unix システムでは、グローバルインストールに sudo が必要な場合があります：

sudo npm install -g telegram-bot-mcp-server

デバッグモード

追加のデバッグ情報を表示するには、NODE_ENV=development を設定します：

NODE_ENV=development npx telegram-bot-mcp-server

📚 使用例

基本的なメッセージ送信

// Through MCP client
await sendMessage({
  chatId: "@username",
  text: "Hello! This is a test message."
});

長いメッセージの処理

// Messages over 4096 characters are automatically split
await sendMessage({
  chatId: "123456789",
  text: "Very long message content..." // Will be split automatically
});

長いキャプション付きの写真

await sendPhoto({
  chatId: "123456789",
  media: "https://example.com/photo.jpg",
  text: "Very long caption..." // Will be split if needed
});

🤝 貢献

1. リポジトリをフォークします
2. フィーチャーブランチを作成します：git checkout -b feature-name
3. 変更を加えます
4. 該当する場合はテストを追加します
5. 変更をコミットします：git commit -am 'Add feature'
6. ブランチにプッシュします：git push origin feature-name
7. プルリクエストを送信します

📄 ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

💬 サポート

• 問題：GitHub Issues
• Telegram API ドキュメント：公式ドキュメント
• MCP プロトコル：Model Context Protocol

☕ プロジェクトを支援する

このプロジェクトが役に立った場合は、開発者への支援をご検討ください。