Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| TELEGRAM_SESSION | No | Custom session name for the Telegram MCP server | |
| TELEGRAM_MAX_WAIT | No | Custom max wait time in seconds (e.g. 86400 for 24 hours) | |
| TELEGRAM_POLL_INTERVAL | No | Custom poll intervals in comma-separated format (e.g. "10,30,60") |
Schema
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| telegram_notify | 发送结构化通知到 Telegram
参数：
- event: 事件类型（completed/error/question/progress）
- summary: 简短总结，必填，限制200字以内
- details: 详细信息，可选
最佳实践：
1. summary 必须简洁明了（1-2句话），说明做了什么、结果如何
2. 不要包含思考过程、不要包含代码片段
3. 需要用户决策时，清晰说明选项
示例：
telegram_notify(
event="completed",
summary="修复了 auth.py:45 的空指针异常，所有测试通过",
details="修改文件: auth.py, test_auth.py\n测试: 12/12 passed"
)
telegram_notify(
event="question",
summary="发现3种修复方案：1)添加空值检查 2)使用Optional类型 3)重构整个模块。推荐方案1，是否继续？"
)
|
| telegram_wait_reply | 等待用户回复（阻塞式轮询）
参数：
- max_wait: 最长等待时间（秒），默认604800（7天/1周）
行为：
- 前10分钟：每30秒检查一次
- 10分钟-1小时：每60秒检查一次
- 1小时以上：每120秒检查一次
- 用户可以按 Ctrl+C 中断等待
- 超时返回 timeout: true
返回：
- reply: 用户回复内容
- timeout: 是否超时
- interrupted: 是否被用户中断
|
| telegram_send | 发送自由格式消息到 Telegram（不推荐，请优先使用 telegram_notify）
自动处理：
- 超过300字自动截断
- 会提示使用 telegram_notify 发送结构化消息
|
| telegram_send_code | 发送代码段到 Telegram（带语法高亮）
⚠️ 使用场景（仅在必要时使用）：
- 遇到关键错误需要展示问题代码
- 修复了重要 bug，需要展示修复方案
- 用户明确要求查看某段代码
- 需要用户 review 关键代码片段
❌ 不要使用的场景：
- 一般性任务完成（使用 telegram_notify）
- 创建了新文件（使用 telegram_send_file）
- 例行操作（使用 telegram_notify 总结即可）
参数：
- code: 代码内容（建议不超过50行）
- language: 编程语言（python/javascript/go/rust/bash/json/yaml等）
- caption: 可选说明文字（建议填写，解释发送这段代码的原因）
示例：
telegram_send_code(
code="def hello():\n print('Hello')",
language="python",
caption="修复了空指针异常的关键函数"
)
|
| telegram_send_image | 发送图片到 Telegram
⚠️ 使用场景：
- 生成了图表、可视化结果
- 创建了截图、示意图
- 需要用户查看图片内容
- 图片格式：PNG, JPG, GIF, WebP 等
参数：
- image_path: 图片文件路径（相对于项目目录或绝对路径）
- caption: 可选说明文字
示例：
telegram_send_image(
image_path="output/chart.png",
caption="性能测试结果图表"
)
|
| telegram_send_file | 发送文件到 Telegram
⚠️ 使用场景（仅在必要时使用）：
- 用户明确要求查看某个文件："查看 config.json"、"发送 main.py 给我"
- 创建了重要的输出文件需要用户确认（如配置文件、报告等）
- 生成了图表、图片等需要展示的文件
- 需要用户下载某个文件进行后续操作
❌ 不要使用的场景：
- 创建普通代码文件（用 telegram_notify 总结即可）
- 修改了文件但不需要用户查看内容
- 例行的文件操作
优先级：
1. 优先使用 telegram_notify 总结文件变更
2. 如果用户明确要求，或确实需要查看，才发送文件
3. 对于代码文件，如果只需要展示关键片段，优先使用 telegram_send_code
参数：
- file_path: 文件路径（相对于项目目录或绝对路径）
- caption: 可选说明文字
支持：
- 文本文件、代码文件
- 图片、PDF、文档等任意文件类型
- 自动处理大文件
示例：
telegram_send_file(
file_path="src/main.py",
caption="修复后的主文件（用户要求查看）"
)
|
| telegram_get_context_info | 获取并发送当前会话的上下文信息到 Telegram
⚠️ 重要：调用此工具时，你应该：
1. 检查系统提供的 token 使用量信息（<budget:token_budget> 标签）
2. 将 token 使用情况包含在发送的信息中
3. 发送完整的上下文信息（会话信息 + token 使用情况）
返回信息应包括：
- 会话 ID 和项目路径
- Token 使用量（已使用 / 总量 / 剩余 / 使用率）
- 会话运行时间
- 系统信息
- Telegram 配置
示例输出格式：
📊 会话上下文信息
🆔 会话: testtg
📁 项目: /path/to/project
💾 Token 使用:
- 已使用: 41,853 tokens
- 总容量: 1,000,000 tokens
- 剩余: 958,147 tokens
- 使用率: 4.2%
⏱️ 运行时间: 15 分钟
🖥️ 系统: Darwin 24.6.0
🐍 Python: 3.14.0
|
| telegram_unattended_mode | 进入无人值守模式 - 智能远程任务循环
工作流程：
1. 执行当前任务
2. 根据情况智能选择通知方式：
- 默认：使用 telegram_notify 发送总结
- 遇到关键问题/错误：使用 telegram_send_code 展示问题代码
- 用户明确要求：使用 telegram_send_file 发送文件
3. 调用 telegram_unattended_mode 等待下一步指令（静默等待，不发送额外提示）
4. 收到指令后执行，重复循环
⚠️ 重要：
- 完成任务后必须调用 telegram_notify 发送结果
- telegram_unattended_mode 本身不发送消息，只等待
- 这样用户每次只收到任务结果，不会有重复的等待提示
📋 通知内容最佳实践：
✅ 优先发送总结：
- "修复了 auth.py 的空指针异常，测试通过"
- "创建了 3 个文件：main.py, utils.py, test.py"
- "代码重构完成，性能提升 30%"
⚠️ 仅在必要时发送代码：
- 遇到无法自动修复的错误，需要展示错误代码
- 修复了关键 bug，展示修复前后对比
- 用户明确要求："查看 main.py"、"发送代码给我"
🎯 智能判断示例：
- 创建新文件 → telegram_notify("创建了 config.json")
- 修复 bug → telegram_notify("修复了登录异常") + 如果复杂就 telegram_send_code
- 用户问"文件内容是什么" → telegram_send_file
退出方式：
- Telegram 发送 "退出" 或 "exit"
- Claude Code 按 Ctrl+C 或 ESC
轮询策略：
- 前10分钟：每30秒检查一次
- 10分钟-1小时：每60秒检查一次
- 1小时以上：每120秒检查一次
参数：
- current_status: 当前任务状态的简短总结（1-2句话）
- max_wait: 每次等待的最长时间（秒），默认604800（7天）
- silent: 静默模式（不发送等待提示，默认 false）
- 首次进入时使用 false（发送提示）
- 后续循环使用 true（减少噪音）
返回：
- next_instruction: 用户的下一步指令
- should_exit: 是否应该退出无人值守模式
- interrupted: 是否被用户中断（Ctrl+C/ESC）
|