Mcp Telegram

Model Context Protocol（MCP） を介して、大規模言語モデルを Telegram に接続します。

Telethon を使用して構築されたこのサーバーにより、AI エージェントは Telegram を操作できます。MTProto を使用したメッセージの送信・編集・削除、チャットの検索、下書きの管理、メディアのダウンロードなどの機能を利用できます。

---

目次

• 🚀 はじめに
  • 前提条件
  • インストール
• ⚙️ 使用方法
  • ログイン
  • MCP サーバーへの接続
• 🧰 利用可能なツール
  • 📨 メッセージングツール
  • 🔍 検索とナビゲーション
  • 📝 下書きの管理
  • 📂 メディアの取り扱い
• 🛠️ トラブルシューティング
• 🤝 貢献
• 📝 ライセンス

---

🚀 はじめに

前提条件

• Python 3.10 以降
• uv は公式の uv ガイドからインストールしてください。

インストール

mcp-telegram CLI ツールをインストールします。

uv tool install mcp-telegram

⚙️ 使用方法

重要

このツールを使用する前に、Telegram の 利用規約を必ず読んで理解してください。このツールを不適切に使用すると、アカウントが制限される場合があります。

mcp-telegram コマンドラインツールが操作の入り口となります。

mcp-telegram --help # See all commands

ログイン

まず、Telegram アカウントで認証します。

mcp-telegram login

この対話型コマンドでは、次の情報の入力を求められます。

• API ID と API Hash： my.telegram.org/apps から取得してください。
• 電話番号： Telegram に登録した電話番号（国際形式。例：+1234567890）。
• 認証コード： 初回ログイン時に Telegram アカウントへ送信されます。
• 2FA パスワード： 二要素認証を有効にしている場合に入力してください。

認証情報は、今後も使用できるようセッションファイルに安全に保存されます。

警告

API 認証情報は非公開にし、決して公開しないでください

メモ

現在のセッションからログアウトするには mcp-telegram logout を、保存済みのセッションデータをすべて削除するには mcp-telegram clear-session を使用してください。

MCP サーバーへの接続

Claude Desktop や Cursor などの MCP クライアントで MCP Telegram を使用するには、MCP サーバーを設定する必要があります。設定方法は、クライアントやオペレーティングシステムによって異なります。

詳しいセットアップ手順については、以下をご覧ください。

• Claude Desktop MCP セットアップガイド
• Cursor MCP ドキュメント

設定ファイルには、次の内容を記述してください。

{
  "mcpServers": {
    "mcp-telegram": {
      "command": "mcp-telegram" /* Use full path if client can't find the command (e.g. "/usr/local/bin/mcp-telegram"). See IMPORTANT section below for full path instructions. */,
      "args": ["start"],
      "env": {
        "API_ID": "<your_api_id>",
        "API_HASH": "<your_api_hash>"
      }
    }
  }
}

メモ

設定ファイルのパスは、OS やクライアントによって異なります。例：

• macOS：~/Library/Application Support/Claude/ または ~/.cursor/
• Windows：%APPDATA%\Claude\ または %APPDATA%\Cursor\

重要

ターミナルからアクセスできるにもかかわらず、クライアントが mcp-telegram を実行できない場合は、実行ファイルのフルパスを指定してみてください。ターミナルで which mcp-telegram（macOS/Linux）または where mcp-telegram（Windows）を実行すると確認できます。設定の command の値をフルパスに置き換えてください。

設定ファイルを保存したら、アプリケーションを再起動してください。

🧰 利用可能なツール

MCP を通じて Telegram を操作する際に使用できるツールの一覧です。

📨 メッセージングツール

ツール	説明
send_message	✉️ 任意のユーザー、グループ、チャンネルにテキストメッセージやファイルを送信します
edit_message	✏️ 送信済みメッセージの内容を編集します
delete_message	🗑️ 1 件または複数のメッセージを削除します
get_messages	📜 高度なフィルタリングオプションを使ってメッセージ履歴を取得します

🔍 検索とナビゲーション

ツール	説明
search_dialogs	🔎 名前またはユーザー名からユーザー、グループ、チャンネルを検索します
message_from_link	🔗 Telegram のリンクを使って特定のメッセージにアクセスします

📝 下書きの管理

ツール	説明
get_draft	📋 任意のチャットの現在のメッセージ下書きを表示します
set_draft	✍️ メッセージの下書きを作成またはクリアします

📂 メディアの処理

ツール	説明
media_download	📸 メッセージから写真、動画、ドキュメントをダウンロードします

メモ

パラメーターの詳細や使用例については、ターミナルで mcp-telegram tools を実行してください。

🛠️ トラブルシューティング

データベースロックエラー

同じセッションファイル を使用して複数の mcp-telegram インスタンスを実行すると、Telethon の SQLite セッションストレージが原因で database is locked エラーが発生することがあります。各セッションファイルを使用するインスタンスは、常に 1 つだけにしてください。

既存のプロセスを強制終了する

停止しない可能性のあるプロセスを終了する必要がある場合：

• macOS / Linux： pkill -f "mcp-telegram"
• Windows： taskkill /F /IM mcp-telegram.exe /T（正確なプロセス名はタスクマネージャーで確認してください）

🤝 コントリビューション

コントリビューションを歓迎します！MCP Telegram の改善にご協力いただける場合は、イシュー、機能リクエスト、プルリクエストをお気軽にお送りください。皆さまからのフィードバックやコントリビューションによって、このプロジェクトをより良いものにできます。

📝 ライセンス

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

---