Telegram MCP サーバー

• Telegram MCP サーバー
  • について
  • MCPとは何ですか?
  • このサーバーは何をしますか?
  • 実用的なユースケース
  • 前提条件
  • インストール
  • 構成
    • Telegram API 設定
    • クロードデスクトップ構成
    • テレグラムの設定
  • 発達
    • はじめる
    • ターミナルでサーバーをデバッグする
    • インスペクターでサーバーをデバッグする
  • トラブルシューティング
    • メッセージ「MCPサーバーmcp-telegramに接続できませんでした」

について

サーバーは、Telegram API と AI アシスタント間のブリッジであり、モデルコンテキストプロトコルに基づいています。

[!重要] このサーバーをご利用になる前に、 Telegram APIの利用規約を必ずお読みください。Telegram APIを不正に使用した場合、アカウントが停止される可能性があります。

MCPとは何ですか?

モデルコンテキストプロトコル（MCP）は、Claude DesktopのようなAIアプリが外部ツールやデータソースに接続できるようにするシステムです。これにより、AIアシスタントがユーザーの制御を維持しながら、ローカルサービスやAPIを明確かつ安全に操作できるようになります。

このサーバーは何をしますか?

現時点では、サーバーは Telegram API への読み取り専用アクセスを提供します。

• [x] ダイアログ（チャット、チャンネル、グループ）のリストを取得します
• [x] 指定されたダイアログ内の（未読）メッセージのリストを取得します
• [ ] チャンネルを既読にする
• [ ] 日付と時刻でメッセージを取得する
• [ ] メディアファイルをダウンロードする
• [ ] 連絡先リストを取得する
• [ ] メッセージの下書き
• ...

実用的なユースケース

• [x] 未読メッセージの要約を作成する
• [ ] 誕生日が近い連絡先を検索し、挨拶の予定を立てる
• [ ] 特定のトピックに関する議論を検索し、要約し、リンクのリストを提供する

前提条件

• uvツール

インストール

[!NOTE] サーバーをすでにインストールしている場合は、 uv tool upgrade --reinstallコマンドを使用して更新できます。

[!NOTE] サーバーを削除する場合は、 uv tool uninstall mcp-telegramコマンドを使用します。

構成

Telegram API 設定

サーバーを使用する前に、Telegram API に接続する必要があります。

1. Telegram APIからAPI IDとハッシュを取得する
2. 次のコマンドを実行します。
   mcp-telegram sign-in --api-id <your-api-id> --api-hash <your-api-hash> --phone-number <your-phone-number>
   API に接続するには、Telegram から受け取ったコードを入力します。2 要素認証を有効にしている場合は、パスワードが必要になることがあります。

[!NOTE] Telegram API からログアウトするには、 mcp-telegram logoutコマンドを使用します。

クロードデスクトップ構成

Claude Desktop が Exa MCP サーバーを認識するように設定します。

1. Claude Desktop 構成ファイルを開きます。
   • MacOSでは、設定ファイルは~/Library/Application Support/Claude/claude_desktop_config.jsonにあります。
   • Windowsでは、構成ファイルは%APPDATA%\Claude\claude_desktop_config.jsonにあります。

   注: claude_desktop_config.json は Claude Desktop アプリの設定内にもあります。

2. サーバー構成を追加する
   { "mcpServers": { "mcp-telegram": { "command": "mcp-server", "env": { "TELEGRAM_API_ID": "<your-api-id>", "TELEGRAM_API_HASH": "<your-api-hash>", }, } } } }

テレグラムの設定

Telegram の API を使用する前に、独自の API ID とハッシュを取得する必要があります。

1. 使用する開発者アカウントの電話番号で Telegram アカウントにログインします。
2. API 開発ツールの下をクリックします。
3. 「新しいアプリケーションを作成」ウィンドウが表示されます。アプリケーションの詳細を入力してください。URLを入力する必要はありません。また、最初の2つのフィールド（アプリケーションタイトルと短縮名）のみ、現在後から変更できます。
4. 最後に「アプリケーションを作成」をクリックしてください。APIハッシュは秘密であり、Telegramでは取り消すことができませんのでご注意ください。どこにも投稿しないでください。

発達

はじめる

1. リポジトリをクローンする
2. 依存関係をインストールする
   uv sync
3. サーバーを実行する
   uv run mcp-telegram --help

ツールはsrc/mcp_telegram/tools.pyファイルに追加できます。

新しいツールを追加する方法:

1. ToolArgsから継承する新しいクラスを作成する
   class NewTool(ToolArgs): """Description of the new tool.""" pass
   クラスの属性はツールの引数として使用されます。クラスのdocstringはツールの説明として使用されます。
2. 新しいクラスにtool_runner関数を実装する
   @tool_runner.register async def new_tool(args: NewTool) -> t.Sequence[TextContent | ImageContent | EmbeddedResource]: pass
   この関数は、TextContent、ImageContent、またはEmbeddedResourceのシーケンスを返す必要があります。この関数は非同期で、新しいクラスの単一の引数を受け入れる必要があります。
3. 完了です。クライアントを再起動すると、新しいツールが利用できるようになります。

検証は、Claude Desktop を通じて、またはツールを直接実行することによって実行できます。

ターミナルでサーバーをデバッグする

ツールを直接実行するには、次のコマンドを使用します。

インスペクターでサーバーをデバッグする

MCPインスペクターは、洗練されたUIを使用してサーバーのデバッグを支援するツールです。実行するには、次のコマンドを使用します。

[!警告] インスペクターで環境変数 TELEGRAM_API_ID と TELEGRAM_API_HASH を定義することを忘れないでください。

トラブルシューティング

メッセージ「MCPサーバーmcp-telegramに接続できませんでした」

Claude Desktop に「MCP サーバー mcp-telegram に接続できませんでした」というメッセージが表示される場合、サーバーの構成が正しくないことを意味します。

次のことを試してください。

• 設定ファイル内のuvバイナリへのフルパスを使用します
• 設定ファイルでクローンしたリポジトリへのパスを確認します