AI导哈

远程AI编码助手控制服务

通过Telegram远程控制AI编码助手（Claude Code/Codex），支持多会话管理、文件操作和长时间无人值守任务。

  • by archetyx
  • Python
  • 本地部署
  • 30 星标
  • 更新于
在 GitHub 查看 batianVolyc/telegram-mcp-server

使用说明

Telegram MCP 服务器

通过Telegram远程控制AI编程助手（Claude Code / Codex）

英语 | 简体中文

为什么选择这个项目？

你是否遇到过这些场景：

  • 💤 睡眠或困倦的表情符号，可译为“打哈欠”或“困了”，但直接作为翻译时，通常保留原样或用“睡”来形象表达其含义。 深夜躺在床上你突然想到一个需要修复的bug，但又不想起身打开笔记本电脑？
  • 🚇 代表地铁的图标。 在你通勤的时候你想让AI帮你重构代码，但你的笔记本电脑又不在身边？
  • 🏢（办公楼/企业标志） 多个Claude代码或Codex会话 在远程服务器上运行，并且您想随时查看它们的进度？
  • ⏰（时钟符号，无具体含义，可理解为“时间”或“提醒时间”的意象） 长时间运行的任务 （测试、构建、重构）这些工作可能需要数小时，但你不想一直坐在电脑前吗？

Telegram MCP 服务器的创建正是为了解决这些问题！

通过MCP（模型上下文协议），此项目使您能够：

  • 📱 随时随地 通过Telegram查看和控制AI编码助手
  • 🔄 旋转（或循环）符号 多会话管理使用 screen 在远程服务器上管理多个项目同时进行
  • 🌙 月亮（或表示夜晚、静谧等意境的符号） 真正的无人值守模式使用智能轮询，最多等待7天，系统资源占用最少
  • 💬 简单的交互通过Telegram发送消息以给AI助手下达下一步指令

非常适合：

  • 全天候（24/7）远程服务器
  • 长时间运行的任务
  • 多个项目的并行开发
  • 随时随地远程工作

特点/特性

  • 🌙（月亮） 真正的无人值守模式 - 使用智能渐进式轮询，最多等待7天
  • 📱 代表手机的符号。 遥控器 - 通过Telegram从任何地方控制AI助手
  • 🔄 旋转或循环（符号本身无特定中文含义，常用于表示重复、循环等概念） 双向沟通 - 发送通知，接收回复，持续对话
  • 📁 文件夹 文件操作 - 查看和下载项目文件
  • 🎯（目标） 多会话管理 - 同时管理多个项目
  • 🤖 机器人 通用支持 - 与Claude Code和Codex均兼容使用

⚡ 快速入门（新用户）

安装与设置（一键完成）

# Use uvx (recommended, no installation needed, always latest version)
uvx --refresh telegram-mcp-server@latest --setup

这将会：

  1. ✅ 从PyPI下载最新版本
  2. ✅ 指导您完成Telegram机器人设置
  3. ✅ 自动配置Claude Code / Codex / Gemini CLI
  4. ✅ 测试连接

就是这个！ 🎉

验证安装

# Check version (should be 0.2.1 or higher)
uvx telegram-mcp-server@latest --version

预期输出：

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

📖 详细安装指南

方法1：使用uvx（推荐）

# Always use latest version
uvx telegram-mcp-server@latest --setup

# Or using pip
pip install telegram-mcp-server

2. 设置

选项A：自动设置（推荐）

telegram-mcp-server --setup

交互式向导将帮助您：

  • 创建Telegram机器人
  • 获取凭据
  • 自动配置AI助手

选项B：手动设置与 mcp add

如果你已经有了你的Telegram机器人令牌（Token）和聊天ID，你可以快速添加使用 mcp add 命令：

克劳德·科德:

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. 使用方法/用途

# Recommended: Start with bypass permissions mode
# Avoid interruptions due to permission confirmations during AI-Telegram interaction
# Note: Cannot run as root due to security mechanisms

# Claude Code
claude --permission-mode bypassPermissions

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

# Gemini CLI (YOLO mode - auto-approve all MCP calls)
gemini --yolo

# In the AI assistant
> 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天：

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

用例

场景1：过夜任务

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

# 8 AM - check results in Telegram

情景2：远程工作

# At office
> Enter unattended mode. Task: refactor database access layer

# On the road - monitor and control via Telegram

场景3：多项目管理（远程服务器+屏幕）

# SSH to remote server
ssh user@server

# Create multiple screen sessions
screen -S project-a
cd /path/to/project-a
TELEGRAM_SESSION="proj-a" claude --permission-mode bypassPermissions
# Ctrl+A D to detach

screen -S project-b
cd /path/to/project-b
TELEGRAM_SESSION="proj-b" codex --dangerously-bypass-approvals-and-sandbox
# Ctrl+A D to detach

# Manage both projects in Telegram
# Sessions keep running even after closing SSH

场景4：深夜卧床

# During the day, start session on server
screen -S night-task
TELEGRAM_SESSION="night-fix" claude --permission-mode bypassPermissions

# At night in bed, send commands via Telegram
/to night-fix Fix null pointer exception in auth.py

# Next morning, check results
/status night-fix

配置

克劳德·科德

支持三种配置范围：

MCP服务器配置:

  • 用户范围： ~/.claude.json - 全局配置
  • 项目范围: .mcp.json - 团队共享
  • 局部范围： .claude.json - 项目特定的

环境变量 （自动配置的）：

  • ~/.claude/settings.json - 包含 MCP_TOOL_TIMEOUT=604800000 （7天超时）

《科德克斯》（Codex）

全局配置： ~/.codex/config.toml

自动包含 tool_timeout_sec = 604800 （7天超时）

环境变量

# Custom session name
TELEGRAM_SESSION="my-task" claude

# Custom max wait time
TELEGRAM_MAX_WAIT=86400 claude  # 24 hours

# Custom poll intervals
TELEGRAM_POLL_INTERVAL="10,30,60" claude

故障排除

问题：Telegram 机器人无响应

# Check logs
tail -f /tmp/telegram-mcp-server.log

# Quick fix
cd telegram-mcp-server
./quick_fix.sh

问题：Codex 60s 超时

# Auto fix
./fix_codex_timeout.sh

问题：会话未注册

# Reconfigure
telegram-mcp-server --setup

文档

要求

  • Python 3.10+（Python 3.10或更高版本）
  • 克劳德·科德（或科德克斯）
  • Telegram账号

贡献

欢迎投稿！详见 `CONTRIBUTING.md` 翻译成中文是：“贡献指南.md” 或 “贡献规范.md”（具体翻译可能根据上下文有所调整，但基本意思是指向一个关于如何为项目做出贡献的指南或规范文件）

许可证

MIT 许可证 - 详见 许可证

支持

  • 🐛 表示“虫子”或“错误（bug）”的意思。 报告问题
  • 💬（这个表情符号通常表示“文字聊天”或“说点什么”的意思，没有直接的中文翻译，但可以根据上下文理解为“来聊聊”或“说点什么吧”等） 讨论
  • ⭐ 如果你觉得有用，请点赞！

让AI编程助手为你工作，而不是你等着它们 🚀 表情符号“🚀”在中文中通常被翻译为“火箭”或保持原样作为表情使用，不直接对应中文词汇，但在这里为了符合翻译要求，可以理解为“🚀（火箭）”。不过，在实际应用中，这个表情常被直接用作表示火箭、快速前进或兴奋等意象。

相关 MCP