claude-ops-telegram-server

claude-ops Telegram MCP サーバー

/ops:ops-inbox スキル用のユーザー認証型 Telegram MCP サーバーです。BotFather のボットではなく、MTProto（gram.js）を介して個人の Telegram アカウントとして認証するため、実際の DM のやり取りを読み取り、返信できます。

ボットではなくユーザー認証を使用する理由

ボットは、2 人のユーザー間のプライベートチャットで送信されたメッセージを読み取れません。ボットに直接送信されたメッセージのみ読み取れます。/ops:ops-inbox のユースケースでは、オーナーの個人受信トレイを管理するため、ユーザーのアカウントとして認証する必要があります。

セットアップ

1. API 認証情報を取得する

https://my.telegram.org/apps にアクセスし、ボットではなく個人用アプリケーションを作成します。以下を取得できます。

• api_id（整数）
• api_hash（32 文字の文字列）

2. 依存関係をインストールする

cd claude-ops/telegram-server
npm install

3. 初回認証（対話形式）

TELEGRAM_API_ID=12345 \
TELEGRAM_API_HASH=abcdef... \
TELEGRAM_PHONE=+15551234567 \
node index.js --auth

スクリプトから SMS コードと、（有効にしている場合は）2FA パスワードの入力を求められます。認証に成功すると、TELEGRAM_SESSION 文字列が出力されます。これを安全に保管してください（セッショントークンです）。

4. Claude Code で MCP サーバーを設定する

~/.claude/settings.json に追加します。

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["/path/to/claude-ops/telegram-server/index.js"],
      "env": {
        "TELEGRAM_API_ID": "${TELEGRAM_API_ID}",
        "TELEGRAM_API_HASH": "${TELEGRAM_API_HASH}",
        "TELEGRAM_SESSION": "${TELEGRAM_SESSION}",
        "TELEGRAM_PHONE": "${TELEGRAM_PHONE}"
      }
    }
  }
}

シークレットマネージャー（Doppler、1Password、direnv など）から環境変数をエクスポートします（絶対にコミットしないでください）。

export TELEGRAM_API_ID="..."
export TELEGRAM_API_HASH="..."
export TELEGRAM_SESSION="..."   # from step 3
export TELEGRAM_PHONE="+1..."
export TELEGRAM_ENABLED=true    # enables in ops-unread detection

MCP サーバーを読み込むため、Claude Code を再起動します。

ツール

ツール	説明
list_dialogs	最近の会話（DM、グループ、チャンネル）を未読数とともに一覧表示します
get_messages	指定したチャットのメッセージを取得します
send_message	チャットまたはユーザーにメッセージを送信します
search_messages	すべての会話を対象に全文検索します

セキュリティ

• TELEGRAM_SESSION を絶対にコミットしないでください。パスワードと同等のものです。
• セッショントークンはデバイスに紐付けられます。盗まれた場合は、Telegram アプリの「設定」→「デバイス」からログアウトしてください。
• 認証情報はすべて環境変数から取得されます。このリポジトリにハードコードされたものはありません。
• サーバーは stdio 経由で実行されます（ローカルのみ）。Telegram 公式 API 以外へのネットワーク公開はありません。

トラブルシューティング

「Session is no longer valid」：node index.js --auth を再実行して、新しいセッションを生成してください。

「TELEGRAM_API_ID is required」：環境変数が MCP サーバーに渡されていません。~/.claude/settings.json の env ブロックを確認してください。

レート制限：Telegram はアカウントごとに制限を適用します。制限に達した場合は、再試行する前に 15～30 分待ってください。