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

| 等待时间 | 检查频率 | 响应延迟 | |-----------|----------------|----------------| | 0 - 30分钟 | 每30秒 | 最长30秒 | | 30 - 60分钟 | 每60秒 | 最长60秒 | | 1小时以上 | 每120秒 | 最长120秒 |

使用场景

场景一：夜间任务

# 晚上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编码助手为你工作，而不是你等待它们 🚀