Telegram MCP Server

Telegram MCP サーバー

AIアシスタント（Claudeなど）がユーザークライアントAPI（ボットAPIではありません）を使用してTelegramアカウントとやり取りできるようにするMCPサーバー。 @mtproto/coreとFastMCPフレームワークを使用して構築されています。

特徴

ツール

• listChannels
  • サーバーのキャッシュに基づいて、アカウントがアクセスできる利用可能な Telegram チャンネル/チャットを一覧表示します。
  • パラメータ:
    • limit (数値、オプション): 返されるチャネルの最大数 (デフォルト: 50)。
  • 出力: ID、タイトル、タイプ、アクセス ハッシュ (該当する場合) を含むチャネル/チャットのリスト。
• searchChannels
  • キャッシュされたチャンネル/チャットを名前に含まれるキーワードで検索します。
  • パラメータ:
    • keywords (文字列): チャンネル名で検索するキーワード。
    • limit (数値、オプション): 返される結果の最大数 (デフォルト: 100)。
  • 出力: 一致するチャネル/チャットのリスト。
• getChannelMessages
  • ID を使用して特定のチャネル/チャットから最近のメッセージを取得します。
  • パラメータ:
    • channelId (数値): チャネル/チャットの数値 ID ( listChannelsまたはsearchChannelsから取得)。
    • limit (数値、オプション): 返されるメッセージの最大数 (デフォルト: 100)。
    • filterPattern (文字列、オプション): テキスト コンテンツによってメッセージをフィルター処理するための JavaScript 互換の正規表現。
  • 出力: ID、日付、テキスト、送信者 ID を含むメッセージのリスト。

前提条件

1. **Node.js:**バージョン 18 以降を推奨します。
2. Telegramアカウント:
   • 有効なTelegramアカウントが必要です。
   • アカウントで**2 段階認証 (2FA)**を有効にする必要があります (設定 → プライバシーとセキュリティ → 2 段階認証)。
3. Telegram API 資格情報:
   • https://core.telegram.org/api/obtaining_api_idで新しいアプリケーションを作成して、 api_idとapi_hashを取得します。

インストール

1. このリポジトリをクローンします:
   git clone https://github.com/your-username/telegram-mcp-server.git # Replace with your repo URL cd telegram-mcp-server
2. 依存関係をインストールします:
   npm install

構成

設定する必要がある 2 つの個別の構成があります。

1. MCP サーバー構成:環境変数を使用して Telegram MCP サーバーを構成します ( .envファイル内または環境内で直接)。
   TELEGRAM_API_ID=YOUR_API_ID TELEGRAM_API_HASH=YOUR_API_HASH TELEGRAM_PHONE_NUMBER=YOUR_PHONE_NUMBER_WITH_COUNTRY_CODE # e.g., +15551234567
   プレースホルダーの値を実際の資格情報に置き換えます。
2. MCP クライアント構成:構成ファイルを変更して、クライアント ソフトウェア (Claude Desktop、Cursor など) が MCP サーバーに接続するように構成します。
   { "mcpServers": { "telegram": { "url": "http://localhost:8080/sse", "disabled": false, "timeout": 30 } } }
   Claude Desktop の場合、構成ファイルは次の場所にあります。
   • macOSの場合: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows の場合: %APPDATA%/Claude/claude_desktop_config.json

   **重要:**変更を適用するには、MCP クライアントを再起動してください。

サーバーの実行

1. **初回ログイン（重要な最初のステップ）：**サーバーを初めて起動する際（またはセッションが期限切れになったり無効になったりした場合）、Telegramで認証する必要があります。ターミナルから直接実行してください。
   npm start
   • サーバーは.envファイルの資格情報を使用します。
   • ターミナルで、Telegram アカウントに送信されたログイン コードと、必要に応じて 2FA パスワードを入力するように求められます。
   • ログインに成功すると、セッションファイル（ ./data/session.json ）が作成されます。このファイルにより、今後はコードやパスワードを入力せずにサーバーに自動的にログインできるようになります。
   • サーバーはチャットのキャッシュ（ ./data/dialog_cache.json ）の作成または読み込みを試みます。初回起動時は、特にチャット数が多い場合は、多少時間がかかることがあります。キャッシュが存在する場合、次回の起動は高速になります。
2. **通常の操作:**プロジェクト ディレクトリでnpm startを実行して、サーバーを手動で起動する必要があります。サーバーが実行される場合、MCP クライアント (例: Claude Desktop) は、構成で指定された URL (デフォルトではhttp://localhost:8080/sse ) を介してサーバーに接続します。

トラブルシューティング

• ログインプロンプト： MCPクライアントから起動した際にサーバーがログインコード/パスワードの入力を要求し続ける場合は、 data/session.jsonファイルが存在し、有効であることを確認してください。セッションを更新するために、 npm start手動で1回実行する必要があるかもしれません。また、MCPクライアントを実行しているユーザーがdataディレクトリの読み取り/書き込み権限を持っているかどうかも確認してください。
• **キャッシュの問題：**チャンネルが古くなっているか欠落しているように見える場合は、 ./data/dialog_cache.jsonを削除し、サーバーを再起動して（手動でnpm start実行）、強制的に完全更新を実行できます。これには時間がかかる場合があります。
• **モジュールが見つかりません:**プロジェクトディレクトリでnpm installを実行していることを確認してください。MCPクライアントがサーバーを起動する場合は、作業ディレクトリが正しく設定されているか、絶対パスを使用していることを確認してください。
• **その他の問題:**その他の問題が発生した場合は、このサーバー リポジトリで問題を自由に開いてください。

Telegram クライアントライブラリ

このリポジトリには、MCPサーバーで使用される基盤ライブラリtelegram-client.jsも含まれています。ライブラリを直接使用する方法（カスタムスクリプトなど）の詳細については、 LIBRARY.mdを参照してください。

ライセンス

このプロジェクトは MIT ライセンスに基づいてライセンスされています - 詳細についてはLICENSEファイルを参照してください。