Telegram MCP Server

🚀 Telegram MCP Server

Telegramを介してAIコーディングアシスタント（Claude Code / Codex）をリモートで制御できます。

English | 简体中文

🚀 クイックスタート

このプロジェクトの目的

以下のようなシチュエーションに遭遇したことはありませんか？

• 💤 深夜、ベッドの中で突然修正が必要なバグを思いついたが、起きてノートパソコンを開きたくない。
• 🚇 通勤中にAIにコードのリファクタリングを依頼したいが、ノートパソコンを持っていない。
• 🏢 リモートサーバーで複数のClaude CodeまたはCodexセッションが実行されており、いつでも進捗状況を確認したい。
• ⏰ 長時間実行されるタスク（テスト、ビルド、リファクタリング）が数時間かかるが、コンピュータの前に座っていたくない。

Telegram MCP Serverはこれらの問題を解決するために作成されました！

このプロジェクトでは、MCP（Model Context Protocol）を通じて以下のことが可能になります。

• 📱 いつでも、どこでもTelegramを介してAIコーディングアシスタントを表示および制御できます。
• 🔄 マルチセッション管理：リモートサーバーでscreenを使用して複数のプロジェクトを同時に管理できます。
• 🌙 真の無人モード：スマートなポーリングで最大7日間待機でき、システムリソースの使用量が最小限です。
• 💬 シンプルなインタラクション：Telegramを介してメッセージを送信して、AIアシスタントに次の指示を与えることができます。

最適なシチュエーション：

• 24時間体制のリモートサーバー
• 長時間実行されるタスク
• 複数プロジェクトの並列開発
• どこからでものリモートワーク

✨ 主な機能

• 🌙 真の無人モード - スマートな段階的ポーリングで最大7日間待機できます。
• 📱 リモート制御 - Telegramを介してどこからでもAIアシスタントを制御できます。
• 🔄 双方向通信 - 通知を送信し、返信を受け取り、継続的な対話が可能です。
• 📁 ファイル操作 - プロジェクトファイルを表示およびダウンロードできます。
• 🎯 マルチセッション管理 - 複数のプロジェクトを同時に管理できます。
• 🤖 汎用サポート - Claude CodeとCodexの両方で動作します。

新規ユーザー向けのクイックスタート

インストールとセットアップ（1コマンド）

# uvxを使用する（推奨、インストール不要、常に最新バージョン）
uvx --refresh telegram-mcp-server@latest --setup

これにより、以下のことが行われます。

1. ✅ PyPIから最新バージョンをダウンロードします。
2. ✅ Telegram Botのセットアップを案内します。
3. ✅ Claude Code / Codex / Gemini CLIを自動構成します。
4. ✅ 接続をテストします。

以上で完了です！ 🎉

インストールの確認

# バージョンを確認する（0.2.1以上である必要があります）
uvx telegram-mcp-server@latest --version

期待される出力：

telegram-mcp-server version 0.2.1
https://github.com/batianVolyc/telegram-mcp-server

📦 インストール

方法1：uvxを使用する（推奨）

# 常に最新バージョンを使用する
uvx telegram-mcp-server@latest --setup

# またはpipを使用する
pip install telegram-mcp-server

セットアップ

オプションA：自動セットアップ（推奨）

telegram-mcp-server --setup

インタラクティブウィザードが以下のことを支援します。

• Telegram Botを作成する
• 資格情報を取得する
• AIアシスタントを自動構成する

オプションB：mcp addを使用した手動セットアップ

既にTelegram BotトークンとチャットIDを持っている場合は、mcp addコマンドを使用してすぐに追加できます。

Claude Code：

claude mcp add \
  --transport stdio \
  telegram \
  --env TELEGRAM_BOT_TOKEN=YOUR_TOKEN_HERE \
  --env TELEGRAM_CHAT_ID=YOUR_CHAT_ID_HERE \
  -- \
  uvx telegram-mcp-server

Codex：

codex mcp add telegram \
  --env TELEGRAM_BOT_TOKEN=YOUR_TOKEN_HERE \
  --env TELEGRAM_CHAT_ID=YOUR_CHAT_ID_HERE \
  -- \
  npx -y telegram-mcp-server

Gemini CLI：

gemini mcp add telegram uvx telegram-mcp-server \
  -e TELEGRAM_BOT_TOKEN=YOUR_TOKEN_HERE \
  -e TELEGRAM_CHAT_ID=YOUR_CHAT_ID_HERE

💡 ヒント：YOUR_TOKEN_HEREとYOUR_CHAT_ID_HEREを実際の値に置き換えてください。

使用方法

# 推奨：パーミッションバイパスモードで起動する
# AIとTelegramのやり取り中にパーミッション確認による中断を避ける
# 注意：セキュリティメカニズムのため、rootとして実行できません

# Claude Code
claude --permission-mode bypassPermissions

# Codex
codex --dangerously-bypass-approvals-and-sandbox

# Gemini CLI（YOLOモード - すべてのMCP呼び出しを自動承認）
gemini --yolo

# AIアシスタント内で
> Enter unattended mode. Task: analyze project structure

Telegramで結果を確認し、会話を続けることができます！

📚 ドキュメント

仕組み

AI Assistant (Claude Code/Codex)
  ↓ MCP Protocol
MCP Server (telegram-mcp-server)
  ├─ 8 tools (notify, wait, file operations, etc.)
  └─ Telegram Bot (background process)
      ↓ Telegram API
Your Telegram Client

核心機能

MCPツール（8つのツール）

• telegram_notify - 構造化された通知を送信する（推奨）
• telegram_wait_reply - ユーザーの返信を待つ（ブロッキングポーリング）
• telegram_unattended_mode - 無人モード（スマートループ）
• telegram_send_code - コードを送信する（構文ハイライト付き）
• telegram_send_image - 画像を送信する
• telegram_send_file - ファイルを送信する
• telegram_send - 自由形式のメッセージを送信する
• telegram_get_context_info - セッションコンテキスト情報を取得する

Telegramコマンド（6つのコマンド）

• /sessions - すべてのセッションを一覧表示する
• /status <id> - セッションのステータスを確認する
• /to <id> <msg> - セッションにメッセージを送信する
• /file <id> <path> - ファイルを表示する
• /delete <id> - セッションを削除する
• /help - ヘルプを表示する

スマートポーリング

段階的なポーリング戦略で、最大7日間待機できます。

使用例

シナリオ1：一晩中実行するタスク

# 午後10時
> Enter unattended mode. Task: run full test suite and fix all errors

# 午前8時 - Telegramで結果を確認する

シナリオ2：リモートワーク

# オフィスで
> Enter unattended mode. Task: refactor database access layer

# 移動中 - Telegramを介して監視および制御する

シナリオ3：マルチプロジェクト管理（リモートサーバー + screen）

# リモートサーバーにSSHで接続する
ssh user@server

# 複数のscreenセッションを作成する
screen -S project-a
cd /path/to/project-a
TELEGRAM_SESSION="proj-a" claude --permission-mode bypassPermissions
# Ctrl+A Dでデタッチする

screen -S project-b
cd /path/to/project-b
TELEGRAM_SESSION="proj-b" codex --dangerously-bypass-approvals-and-sandbox
# Ctrl+A Dでデタッチする

# Telegramで両方のプロジェクトを管理する
# SSHを閉じた後もセッションは実行され続けます

シナリオ4：深夜、ベッドの中

# 日中にサーバーでセッションを開始する
screen -S night-task
TELEGRAM_SESSION="night-fix" claude --permission-mode bypassPermissions

# 夜、ベッドの中でTelegramを介してコマンドを送信する
/to night-fix Fix null pointer exception in auth.py

# 翌朝、結果を確認する
/status night-fix

設定

Claude Code

3つの設定スコープをサポートしています。

MCPサーバー設定：

• ユーザースコープ：~/.claude.json - グローバル設定
• プロジェクトスコープ：.mcp.json - チーム共有
• ローカルスコープ：.claude.json - プロジェクト固有の設定

環境変数（自動構成）：

• ~/.claude/settings.json - MCP_TOOL_TIMEOUT=604800000（7日間のタイムアウト）を含む

Codex

グローバル設定：~/.codex/config.toml

自動的にtool_timeout_sec = 604800（7日間のタイムアウト）が含まれます。

環境変数

# カスタムセッション名
TELEGRAM_SESSION="my-task" claude

# カスタム最大待機時間
TELEGRAM_MAX_WAIT=86400 claude  # 24時間

# カスタムポーリング間隔
TELEGRAM_POLL_INTERVAL="10,30,60" claude

トラブルシューティング

問題：Telegram Botが応答しない

# ログを確認する
tail -f /tmp/telegram-mcp-server.log

# クイックフィックス
cd telegram-mcp-server
./quick_fix.sh

問題：Codexが60秒でタイムアウトする

# 自動修正
./fix_codex_timeout.sh

問題：セッションが登録されていない

# 再構成する
telegram-mcp-server --setup

その他のドキュメント

• Configuration Guide - 詳細な設定
• Polling Mechanism - スマートポーリングの説明
• Troubleshooting - 一般的な問題
• How MCP Works - MCPの仕組み

必要条件

• Python 3.10以上
• Claude CodeまたはCodex
• Telegramアカウント

貢献方法

貢献を歓迎します！ CONTRIBUTING.mdを参照してください。

📄 ライセンス

MITライセンス - LICENSEを参照してください。

サポート

• 🐛 問題報告
• 💬 ディスカッション
• ⭐ 役に立った場合はスターをつけてください！

AIコーディングアシスタントをあなたのために働かせましょう。あなたがアシスタントを待つのではなく！ 🚀