Telegram MCP Server

Telegram MCP サーバー

MCP（Multi-Client Protocol）を通じて、連絡先の管理、メッセージの送信、チャンネル情報の取得を行うさまざまなツールを提供する、強力な Telegram 統合サーバーです。

機能

• 連絡先の管理

  • 連絡先の一覧を取得
  • 連絡先を検索
  • 最近のやり取りを取得

• メッセージ

  • 名前または電話番号で連絡先にメッセージを送信
  • 日付範囲で絞り込んだチャット履歴を取得
  • 最近のやり取りを表示

• チャンネル機能

  • チャンネルの投稿を取得
  • チャンネルを検索
  • チャンネル情報を表示
  • 日付範囲で投稿を絞り込み

前提条件

• Python 3.8 以降
• Node.js 14 以降（npx でインストールする場合）
• Telegram API 認証情報（api_id と api_hash）
• Telegram アカウント

インストール

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

git clone https://github.com/yourusername/telegram-MCP-server.git
cd telegram-MCP-server

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

uv venv .venv  # Create a virtual environment
source .venv/bin/activate  # Activate it (Linux/macOS)
.\venv\Scripts\activate  # Activate it (Windows)
uv pip install .

3. Telegram API ID と API Hash を取得します。

• https://my.telegram.org にアクセスします
• 電話番号でログインします
• 「API development tools」をクリックします
• 必要な項目を入力します（アプリのタイトルと短縮名は任意のものを使用できます）
• 送信すると、API ID と API Hash が表示されます

4. プロジェクトのルートに、Telegram の認証情報を記載した .env ファイルを作成します。

TG_API_ID=your_api_id
TG_API_HASH=your_api_hash
phone=your_phone_number  # Format: +1234567890

5. 初回のみ、Telegram の認証を行います。

uv run telegram_auth.py

プロンプトが表示されたら、Telegram 経由で受け取ったコードを入力します。

Cursor/Claude Desktop との統合

以下の JSON を、適切な {{PATH}} の値に置き換えてコピーします。

{
  "mcpServers": {
    "telegram": {
      "command": "{{PATH_TO_UV}}", // Run `which uv` and place the output here
      "args": [
        "--directory",
        "{{PATH_TO_SRC}}\\telegram-mcp-server", // cd into the repo, run `pwd` and enter the output here + "/whatsapp-mcp-server"
        "run",
        "main.py"
      ]
    }
  }
}

Claude の場合は、Claude Desktop の設定ディレクトリに claude_desktop_config.json という名前で保存します。

~/Library/Application Support/Claude/claude_desktop_config.json

Cursor の場合は、Cursor の設定ディレクトリに mcp.json という名前で保存します。

~/.cursor/mcp.json

ツールのドキュメント

get_contacts()

名前、電話番号、ユーザー名を含む、Telegram の連絡先一覧を返します。

send_message_by_identifier(identifier: str, message: str)

名前または電話番号で識別される連絡先にメッセージを送信します。

• identifier：連絡先の名前または電話番号
• message：送信するテキストメッセージ

get_last_interaction(identifier: str)

特定の連絡先と最後にやり取りしたメッセージを返します。

• identifier：連絡先の名前または電話番号

get_chat_history(identifier: str, start_date: str = None, end_date: str = None, limit: int = 20)

指定した期間内の連絡先とのチャット履歴を取得します。

• identifier：連絡先の名前または電話番号
• start_date：開始日（省略可能、YYYY-MM-DD）
• end_date：終了日（省略可能、YYYY-MM-DD）
• limit：返すメッセージの最大数

get_channel_posts(channel_name: str, start_date: str = None, end_date: str = None, limit: int = 20)

Telegram チャンネルの投稿を取得します。

• channel_name：チャンネルのユーザー名または名前
• start_date：開始日（省略可能、YYYY-MM-DD）
• end_date：終了日（省略可能、YYYY-MM-DD）
• limit：返す投稿の最大数

エラー処理

サーバーには、以下を対象とする包括的なエラー処理が含まれています。

• 無効な認証情報
• ネットワークの問題
• レート制限
• 無効なパラメーター
• 権限エラー

セキュリティに関する考慮事項

• API 認証情報を安全に保管してください
• .env ファイルを決して共有しないでください
• 本番環境では環境変数を使用してください
• 本番環境で使用する場合は、レート制限を実装してください
• 使用状況を監視し、ログを記録してください

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更をコミットします
4. ブランチにプッシュします
5. プルリクエストを作成します

ライセンス

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

謝辞

• Telegram API との統合に使用する Telethon ライブラリ
• サーバーフレームワークの FastMCP