MCPテレグラム

モデルコンテキストプロトコル (MCP)を介して大規模言語モデルを Telegram に接続します。

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

🚀 はじめに

前提条件

Python 3.10以上
uv公式 uv ガイドに従ってインストールします。

インストール

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

uv tool install mcp-telegram

⚙️ 使用方法

[!重要] このツールを使用する前に、Telegramの利用規約をよく読んで理解してください。このツールを不正に使用した場合、アカウントが制限される可能性があります。

mcp-telegramコマンドラインツールがエントリポイントになります。

mcp-telegram --help # See all commands

API ID と API ハッシュ: my.telegram.org/appsから取得します。
電話番号: Telegram に登録した電話番号 (国際形式、例: +1234567890 )。
**確認コード:**初回ログイン時に Telegram アカウントに送信されます。
2FA パスワード: 2 要素認証が有効になっている場合。

資格情報は、将来の使用に備えてセッションファイルに安全に保存されます。

[!警告] API 認証情報は非公開にし、公開しないでください。

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

MCPサーバーに接続する

Claude DesktopやCursorなどのMCPクライアントでMCP Telegramを使用するには、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>"
      }
    }
  }
}

[!Note] 設定パスはOSとクライアントによって異なります。例:
macOS: ~/Library/Application Support/Claude/または~/.cursor/
Windows: %APPDATA%\Claude\または%APPDATA%\Cursor\

[!IMPORTANT] ターミナルからアクセスできるにもかかわらず、クライアントが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`	📸 メッセージから写真、ビデオ、ドキュメントをダウンロードする

[!Note] 詳細なパラメータ情報と使用例については、ターミナルで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ファイルを参照してください。