星战科技xingzhan.cloud
返回市场
电报-MCP服务器

电报-MCP服务器

作者：batianVolyc21 星标更新：2025-10-22
安装使用来源：spider==github.com

项目介绍

Telegram MCP 服务器

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

PyPI Python License

English | 简体中文

为什么需要这个项目？

你是否遇到过以下场景：

  • 💤 深夜躺在床上，突然想到一个需要修复的错误，但不想起床打开笔记本电脑？
  • 🚇 通勤途中，希望 AI 能帮你重构代码，但笔记本不在身边？
  • 🏢 多个 Claude Code 或 Codex 会话在远程服务器上运行，想随时查看它们的进度？
  • ⏰ 长时间任务（测试、构建、重构）需要数小时，但不想坐在电脑前等待？

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

通过 MCP（模型上下文协议），此项目允许你：

  • 📱 随时随地通过 Telegram 查看和控制 AI 编码助手
  • 🔄 多会话管理：使用远程服务器上的 screen 同时管理多个项目
  • 🌙 真正的无人值守模式：智能轮询等待长达 7 天，占用极少系统资源
  • 💬 简单的交互：通过 Telegram 发送消息给 AI 助手以获取下一步指令

适用于：

  • 24/7 远程服务器
  • 长时间任务
  • 多项目并行开发
  • 从任何地方远程工作

特性

  • 🌙 真正的无人值守模式 - 智能渐进式轮询等待长达 7 天
  • 📱 远程控制 - 通过 Telegram 从任何地方控制 AI 助手
  • 🔄 双向通信 - 发送通知，接收回复，持续对话
  • 📁 文件操作 - 查看和下载项目文件
  • 🎯 多会话管理 - 同时管理多个项目
  • 🤖 通用支持 - 支持 Claude Code 和 Codex

⚡ 快速开始（新用户）

安装与设置（一条命令）

# 使用 uvx（推荐，无需安装，始终最新版本）
uvx --refresh telegram-mcp-server@latest --setup

这将：

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

就这样！ 🎉

验证安装

# 检查版本（应为 0.2.1 或更高）
uvx telegram-mcp-server@latest --version

预期输出：

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

📖 详细安装

方法 1：使用 uvx（推荐）

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

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

2. 设置

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

telegram-mcp-server --setup

交互式向导将帮助你：

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

选项 B：手动设置 mcp add

如果你已经拥有 Telegram 机器人令牌和聊天 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 助手（Claude Code/Codex）
  ↓ MCP 协议
MCP 服务器（telegram-mcp-server）
  ├─ 8 个工具（通知、等待、文件操作等）
  └─ Telegram 机器人（后台进程）
      ↓ 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 秒

使用案例

场景 1：夜间任务

# 晚上 10 点
> 进入无人值守模式。任务：运行完整的测试套件并修复所有错误

# 上午 8 点 - 在 Telegram 中检查结果

场景 2：远程工作

# 在办公室
> 进入无人值守模式。任务：重构数据库访问层

# 在路上 - 通过 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 修复 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 机器人不响应

# 检查日志
tail -f /tmp/telegram-mcp-server.log

# 快速修复
cd telegram-mcp-server
./quick_fix.sh

问题：Codex 60 秒超时

# 自动修复
./fix_codex_timeout.sh

问题：会话未注册

# 重新配置
telegram-mcp-server --setup

文档

要求

  • Python 3.10+
  • Claude Code 或 Codex
  • Telegram 账户

贡献

欢迎贡献！参阅 CONTRIBUTING.md

许可证

MIT 许可证 - 详见 LICENSE

支持

让 AI 编码助手为你工作，而不是你等待它们 🚀