Telegram MCP Server

🚀 Telegram MCP Server

本項目可通過Telegram遠程控制AI編碼助手（Claude Code / Codex），讓你隨時隨地掌控AI編碼工作，擺脫時間和空間的限制。

English | 簡體中文

🚀 快速開始

安裝與設置（一鍵完成）

# 使用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

✨ 主要特性

• 🌙 真正的無人值守模式：通過智能漸進式輪詢，可等待長達7天。
• 📱 遠程控制：通過Telegram在任何地方控制AI助手。
• 🔄 雙向通信：發送通知、接收回復、進行連續對話。
• 📁 文件操作：查看和下載項目文件。
• 🎯 多會話管理：同時管理多個項目。
• 🤖 通用支持：支持Claude Code和Codex。

📦 安裝指南

方法一：使用uvx（推薦）

# 始終使用最新版本
uvx telegram-mcp-server@latest --setup

# 或者使用pip
pip install telegram-mcp-server

2. 設置

選項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 替換為你的實際值

3. 使用

# 推薦：以繞過權限模式啟動
# 避免在AI與Telegram交互期間因權限確認而中斷
# 注意：由於安全機制，不能以root身份運行

# Claude Code
claude --permission-mode bypassPermissions

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

# Gemini CLI（YOLO模式 - 自動批准所有MCP調用）
gemini --yolo

# 在AI助手中
> 進入無人值守模式。任務：分析項目結構

在Telegram中查看結果並繼續對話！

💻 使用示例

基礎用法

# 在AI助手中啟動無人值守任務
> 進入無人值守模式。任務：分析項目結構

高級用法

# 多項目管理示例，在遠程服務器上使用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後會話仍會繼續運行

📚 詳細文檔

工作原理

AI助手（Claude Code/Codex）
  ↓ MCP協議
MCP服務器（telegram-mcp-server）
  ├─ 8個工具（通知、等待、文件操作等）
  └─ Telegram Bot（後臺進程）
      ↓ Telegram API
你的Telegram客戶端

核心特性

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天：

使用場景

場景一：夜間任務

# 晚上10點
> 進入無人值守模式。任務：運行完整測試套件並修復所有錯誤

# 早上8點 - 在Telegram中檢查結果

場景二：遠程工作

# 在辦公室
> 進入無人值守模式。任務：重構數據庫訪問層

# 在路上 - 通過Telegram監控和控制

場景三：多項目管理（遠程服務器 + 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後會話仍會繼續運行

場景四：深夜臥床

# 白天，在服務器上啟動會話
screen -S night-task
TELEGRAM_SESSION="night-fix" claude --permission-mode bypassPermissions

# 晚上在床上，通過Telegram發送命令
/to night-fix 修復auth.py中的空指針異常

# 第二天早上，檢查結果
/status night-fix

配置

Claude Code

支持三種配置範圍：

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

文檔

• 配置指南 - 詳細配置
• 輪詢機制 - 智能輪詢解釋
• 故障排除 - 常見問題
• MCP工作原理 - 技術架構

🔧 技術細節

系統要求

• Python 3.10+
• Claude Code或Codex
• Telegram賬戶

貢獻

歡迎貢獻！請參閱 CONTRIBUTING.md

📄 許可證

本項目採用MIT許可證 - 詳情請參閱 LICENSE

支持

• 🐛 報告問題
• 💬 討論
• ⭐ 如果你覺得有用，請給項目加星！

讓AI編碼助手為你工作，而不是你等待它們 🚀