Telegram MCP Server

🚀 Telegram MCP サーバーガイド

Telegram MCP サーバーは、Telegram API と AI アシスタント（Claude Desktop など）をつなぐ橋渡しの役割を果たします。このサーバーは一連のツールを提供することで、AI アシスタントが Telegram のメッセージや機能とやり取りできるようにします。

⚠️ 重要注意事項

• Telegram API を使用する際には、その利用規約を厳守してください。
• API キーやその他の機密情報の安全を確保し、漏洩を防いでください。

🚀 クイックスタート

Telegram MCP サーバーを使用する前に、いくつかの前提条件を満たす必要があります。また、サーバーのインストール、更新、アンインストールの手順を紹介します。

前提条件

• uv ツールをインストールし、設定する
• Telegram 開発者アカウントを取得する
• 新しい Telegram アプリケーションを作成し（API ID と HASH を取得するため）

インストール手順

1. 以下のコマンドを使用してリポジトリをクローンします。

uv clone git+https://github.com/sparfenyuk/mcp-telegram.git

2. ターミナルでサーバーを起動します。

cd mcp-telegram
uv run mcp-telegram

3. 以下のコマンドでヘルプ情報を取得します。

uv run mcp-telegram --help

更新手順

uv sync

アンインストール手順

uv uninstall mcp-telegram

✨ 主な機能

MCP プロトコル

MCP（Model Context Protocol）は、AI アプリケーションと外部ツールやサービス間の通信に使用されるプロトコルです。MCP を通じて、AI アシスタントは以下のことができます。

• Telegram アカウントを操作する
• メッセージを送受信する
• 会話を管理する
• Telegram の高度な機能を使用する

サーバー機能

実装済みの機能

• 会話を一覧表示する（未読での絞り込みも可能）
• メッセージを送受信する
• 新しい会話を作成する
• チャット履歴を取得する
• Telegram のファイルやメディアを操作する

未実装の機能

• グループ管理
• チャンネル管理
• 定期タスク
• API ログ記録

💻 使用例

未読メッセージの要約作成

MCP サーバーを使用して、Telegram から未読メッセージを取得し、Claude Desktop で要約を生成します。

自動返信ボット

サーバーツールを設定して、自動メッセージ応答機能を実現します。

チャット履歴の一括処理

MCP サーバーを使用して、大量のチャットデータをエクスポートし、管理します。

📚 ドキュメント

設定ガイド

Telegram API 設定

1. Telegram アカウントにログインし、開発者ツール画面にアクセスします。
2. 新しいアプリケーションを作成し、API ID と API HASH を取得します。

Claude Desktop 設定

設定ファイル（通常は ~/.config/claude/tools.yaml）を編集し、以下の内容を追加します。

full/path/to/uv: &uvcli
  cli: uv
  args:
    - run
    - mcp-telegram

パスが正しいことを確認してください。

開発ガイド

入門手順

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

uv clone git+https://github.com/sparfenyuk/mcp-telegram.git

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

uv sync

3. サーバーを起動し、ヘルプ情報を表示します。

uv run mcp-telegram --help

新しいツールの追加

1. src/mcp_telegram/tools.py で新しいクラスを作成します。

class NewTool(Tool):
    """新しいツールの機能を説明する"""
    async def _run(self, args: List[str], stdin: Optional[bytes]) -> Tuple[int, bytes]:
        # 具体的な機能を実装する

2. 以下のデコレータを使用してツールを登録します。

@toolkit_register
class NewTool(Tool):
    pass

デバッグ方法

ターミナルでのデバッグ

以下のコマンドを実行して、ログ情報を表示します。

uv run mcp-telegram --log=all

Inspector ツール

以下のコマンドを実行して、デバッグツールを起動します。

uv inspect mcp-telegram

トラブルシューティング

接続問題

1. uv バイナリファイルのパスが正しいことを確認します。
2. サーバーが正常に起動していることを確認します。

ログ情報

以下のコマンドを実行して、ログを表示し、詳細な情報を取得します。

uv run mcp-telegram --log=all

以上のガイドを参考にすることで、Telegram MCP サーバーを簡単に設定し、使用することができます。さらなる支援が必要な場合は、公式ドキュメントを参照するか、開発者コミュニティに問い合わせてください。