Telegram MCP Server

Telegram Bot APIを介してTelegramとやり取りするためのMCPサーバー。このサーバーは、LLMクライアントにメッセージの送信、利用可能な最新メッセージの読み取り、チャット情報の取得を行うためのツールセットを提供します。

機能

サーバーは3つのMCPツールを提供します：

• send_message — 指定されたTelegramチャットにテキストメッセージを送信します。

• get_recent_messages — 指定されたチャットから利用可能な最新メッセージを取得します。

• get_chat_info — Telegramチャットの基本情報を返します。

サーバーはstdioトランスポートを使用するため、別途HTTPサーバーを用意しなくてもMCP Inspectorや他のMCPクライアントに接続できます。

Related MCP server: agent-telegram-mcp

アーキテクチャ

MCP client / MCP Inspector
            │
            │ MCP over stdio
            ▼
      src/server.py
            │
            ▼
   src/telegram_client.py
            │
            │ HTTPS
            ▼
    Telegram Bot API

server.pyはMCPインターフェースとツールの登録を担当します。

telegram_client.pyはTelegram Bot APIとのHTTP通信をカプセル化します。

config.pyは環境変数からトークンを読み込みます。

スタック

• Python 3.10+

• MCP Python SDK 2.x

• Telegram Bot API

• httpx

• python-dotenv

プロジェクト構造

telegram-mcp/
├── src/
│   ├── __init__.py
│   ├── config.py
│   ├── telegram_client.py
│   └── server.py
├── .env.example
├── .gitignore
├── requirements.txt
└── README.md

要件

• Python 3.10以降

• @BotFatherで作成されたTelegramボット

• Node.jsとnpx — mcp dev経由でMCP Inspectorを使用する場合のみ必要

インストール

リポジトリをクローンし、そのディレクトリに移動します：

git clone <repository-url>
cd telegram-mcp

仮想環境を作成します：

python3 -m venv .venv
source .venv/bin/activate

依存関係をインストールします：

pip install -r requirements.txt

Telegramボットの設定

1. Telegramを開き、@BotFatherを検索します。

2. /newbotを実行します。

3. ボットを作成し、Bot APIトークンを取得します。

4. トークンをソースコードやGitに追加しないでください。

.envファイルを作成します：

cp .env.example .env

トークンを指定します：

TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here

.envは.gitignoreに追加されています。

チャットの準備

個人チャット

1. 作成したボットを開きます。

2. Startを押すか、ボットにメッセージを送信します。

3. get_recent_messagesをテストするために、いくつかのテキストメッセージを送信します。

グループ

1. テスト用グループを作成します。

2. グループにボットを追加します。

3. ボットがグループの通常メッセージを表示できるようにするには、@BotFatherでプライバシーモードを無効にします（/setprivacy → Disable）。

4. グループにいくつかのメッセージを送信します。

chat_idを取得するには、ボットが目的のチャットからメッセージを受け取った後に、get_chat_infoまたはget_recent_messagesを呼び出すと便利です。

起動

プロジェクトのルートディレクトリから：

python src/server.py

サーバーはstdio経由で動作し、MCP接続を待機します。そのため、起動後にターミナルに通常の出力が表示されないのは正常な動作です。

開発と確認にはMCP CLIを使用できます：

mcp dev src/server.py

このコマンドはサーバーとMCP Inspectorを起動します。Inspectorはnpxを使用するため、Node.jsがPATHに含まれている必要があります。

MCPツール

send_message

Telegramにテキストメッセージを送信します。

パラメータ：

chat_id: string — ID чата
text: string — текст сообщения

例：

chat_id: 123456789
text: Привет! Сообщение отправлено через MCP.

サーバーは送信確認とmessage_idを返します。

get_recent_messages

指定されたチャットの利用可能な最新メッセージを取得します。

パラメータ：

chat_id: string — ID чата
limit: integer — количество сообщений, по умолчанию 10

limitは1から100の範囲に制限されます。

例：

chat_id: 123456789
limit: 10

結果には、各利用可能なメッセージの送信者とテキストが含まれます。

get_chat_info

チャットの基本情報を取得します。

パラメータ：

chat_id: string — ID чата

応答には、ID、タイプ、名前、ユーザー名、名、姓など、利用可能なフィールドが表示されます。

メッセージ取得の仕組み

Telegram Bot APIは、ボットにチャット履歴を任意に読み取るための個別のメソッドを提供しません。受信メッセージを取得するために、サーバーはgetUpdatesを使用します。

get_recent_messagesは、利用可能な最新のアップデートを最大100件取得し、その後chat_idでフィルタリングします。そのため、このツールはTelegramがアップデートキューを通じてボットに提供するメッセージを扱い、チャットの完全な履歴ではありません。

つまり、このツールは全履歴にアクセスできるTelegramクライアントの代わりにはなりません。テストするには、ボットをチャットに追加した後にメッセージを送信し、その後get_recent_messagesを呼び出せば十分です。

重要：getUpdatesはアクティブなwebhookと同時に使用できません。ボットにwebhookが設定されている場合は、まずそれを削除してから、getUpdatesによるロングポーリングでアップデートを受信できるようにしてください。

シナリオ例

1. MCP Inspectorを起動します。

2. src/server.pyを接続します。

3. 以下のツールが利用可能であることを確認します：

   • send_message

   • get_recent_messages

   • get_chat_info

4. get_chat_infoを呼び出してチャットへの接続を確認します。

5. send_messageを呼び出し、メッセージがTelegramに表示されることを確認します。

6. Telegramにいくつかのメッセージを送信します。

7. get_recent_messagesを呼び出し、取得したメッセージリストを確認します。

セキュリティ

Telegram Bot APIトークンは、環境変数TELEGRAM_BOT_TOKENを介してのみ渡されます。

実際の.envはGitに含めてはいけません。リポジトリには、動作トークンを含まない.env.exampleのみが保存されます。

制限事項

• ボットはBot APIを介してTelegramチャットの全履歴にアクセスできません。

• get_recent_messagesは利用可能なボットアップデートを扱います。

• グループでは、ボットが受信するメッセージのセットはTelegramのプライバシー設定に依存します。

• getUpdatesとwebhookは、アップデートを取得する方法として相互に排他的です。