Telegram

Telegram MCP サーバー

英語版 | ロシア語版

Model Context Protocol（MCP）を通じて Telegram API を操作するサーバーです。AI エージェントやその他の MCP クライアントが Telegram とやり取りできます。

要件

• Node.js 14+（またはそれ以降）
• npm
• Telegram の API ID と API Hash

インストール

1. リポジトリをクローンします：

   git clone https://github.com/kdoronin/telegram_mcp
   cd telegram-mcp
   

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

   npm install
   

   (必要なパッケージ（gramjs、@modelcontextprotocol/sdk、zod など）がインストールされます。)

3. .env ファイルを作成して設定します：

   # Copy the example .env file
   cp .env.example .env
   

   .env ファイルを編集し、API_ID と API_HASH を指定します。

4. API ID と API Hash を取得します：

   • my.telegram.org にアクセスします
   • アカウントにログインします
   • 「API development tools」に移動します
   • 新しいアプリケーションを作成します
   • api_id と api_hash を .env ファイルにコピーします

実行

実行に関する重要な注意

メインサーバーファイル mcp-server.js はプロジェクトのルートにあるため、パスの問題なく実行できます。

オプション 1：npm 経由（推奨）

npm run mcp    # Run from the project root directory

オプション 2：node を直接実行

# Run from the project root directory
node mcp-server.js

オプション 3：実行可能ファイルとして実行

# From the project root
./mcp-server.js

オプション 4：グローバルインストール後に実行

npm install -g .   # Install the package globally
telegram-mcp       # Run the globally installed package

MCP クライアントとの統合

Cursor の設定

1. Cursor の設定を開きます
2. Features -> MCP Servers に移動します
3. 「Add new MCP server」をクリックします
4. サーバーを設定します：
   • 名前：telegram（または任意の名前）
   • タイプ：command
   • コマンド：node /full/path/to/project/mcp-server.js
   • 代わりに、npx telegram-mcp を指定することもできます（グローバルインストール後）

Claude Desktop の設定

1. Claude Desktop の設定を開きます
2. Tools -> MCP に移動します
3. 「Add New Server」をクリックします
4. サーバーを設定します：
   • 名前：telegram（または任意の名前）
   • タイプ：command
   • コマンド：node /full/path/to/project/mcp-server.js
   • 代わりに、npx telegram-mcp を指定することもできます（グローバルインストール後）

動作確認

サーバーの起動時に、次の処理が行われます：

1. .env ファイルから設定を読み込みます
2. 保存済みのセッションを確認します
3. セッションがない場合は、新しいセッションの作成を促します（電話番号と確認コードを入力する必要があります）

利用可能なツール

MCP サーバーでは、次のツールを利用できます：

• getDialogs：ユーザーのダイアログ（チャット）の一覧を取得します。
  • パラメーター：session（文字列、必須）、limit（整数、省略可、デフォルト：100）。
• getMessages：指定したチャットからメッセージを取得します。
  • パラメーター：session（文字列、必須）、chatId（文字列、必須）、limit（整数、省略可、デフォルト：100）。
• sendMessage：指定したチャットにメッセージを送信します。
  • パラメーター：session（文字列、必須）、chatId（文字列、必須）、message（文字列、必須）。
• executeMethod：任意の Telegram API メソッドを実行します（注意して使用してください）。
  • パラメーター：session（文字列、必須）、method（文字列、必須）、params（オブジェクト、省略可）。

注：session パラメーターには通常、国際形式のユーザーの電話番号（例：+79001234567）を指定します。

プロンプトでの使用例

Using the telegram.getDialogs tool for session +79001234567, show me the last 5 chats.

With telegram.sendMessage for session +79001234567, send the message "Hello from my AI assistant!" to chat with ID 'username_or_chat_id'.

認証

session（電話番号）を初めて使用するとき、サーバーは実行中のコンソールに確認コードを要求します。Telegram から届いたコードを入力してセッションを認証してください。

2 要素認証（2FA）が有効になっている場合は、Telegram のパスワードも入力する必要があります。パスワードを間違えると、再入力を求められます（最大 3 回）。

認証が成功すると、セッションは sessions/ ディレクトリ内のファイルに保存され、以降のリクエストで使用されます。

セッションファイルの構造

セッションは sessions/ ディレクトリに、電話番号をファイル名にした JSON ファイル（例：+79001234567.json）として保存されます。各ファイルには次の内容が含まれます：

• セッション文字列（暗号化された認証トークン）
• 作成／更新のタイムスタンプ

トラブルシューティング

1. エラー「Your API ID or Hash cannot be empty or undefined」

   • .env ファイルがプロジェクトのルートにあることを確認してください
   • API_ID と API_HASH が正しく指定されていることを確認してください
   • プロジェクトのルートディレクトリからサーバーを実行してください

2. サーバーが保存済みのセッションを認識しない

   • 実行パスを確認してください（プロジェクトのルートから実行する必要があります）
   • sessions/ ディレクトリにセッションファイルがあることを確認してください
   • npm run mcp を実行してみてください

3. 認証エラー

   • 2FA パスワードを間違えて入力した場合、再入力を求められます
   • 試行回数を使い切った場合は、セッションファイルを削除してもう一度お試しください

セキュリティ

• API ID と API Hash を第三者と共有しないでください。
• 信頼できる環境でサーバーを実行してください。
• セッションファイルには機密データが含まれています。 安全な場所に保管し、共有しないでください。
• executeMethod ツールでは、任意の Telegram API メソッドを実行できます。破壊的な操作を実行する可能性があるため、注意して使用してください。

ライセンス

MIT