AI导哈

Telegram消息代理服务

一个通过HTTP流式传输实现Telegram消息、媒体、进度更新和审批提示发送的轻量级无状态服务。

  • by ArasanDev
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 AI-with-Tamil/telegram-mcp

使用说明

电报mcp

telegram-mcp 是一个FastMCP服务器，允许MCP代理通过流式HTTP将消息、媒体、进度更新和批准提示发送到一个Telegram聊天中。

它故意是单聊和无状态的：

  • Telegram凭据已上线 .env
  • 代理人拥有任何长期有效的 message_id 它想重复使用
  • 如果代理使用审批流，则它拥有 next_offset

先决条件

  1. 使用BotFather创建一个Telegram机器人，并开始与它聊天。
  2. 如果你打算使用 tg_request_approval，确保bot使用的是轮询，而不是webhooks。
  3. 创建 telegram-mcp/.env 与：
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=

笔记：

  • TELEGRAM_BOT_TOKEN 和 TELEGRAM_CHAT_ID 启动时需要。
  • 如果配置了webhook， tg_request_approval 返回： Error: getUpdates cannot be used while a webhook is configured. Delete the webhook or switch architectures.

安装并运行

uv sync
uv run telegram-mcp

服务器正在监听 http://127.0.0.1:8000/mcp.

克劳德桌面

添加此MCP条目：

{
  "mcpServers": {
    "telegram": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

更新配置后重新启动Claude Desktop。

工具

tg_send_message

向配置的聊天室发送文本。

示例输入：

{
  "text": "received your message",
  "parse_mode": "plain",
  "reply_to_message_id": null
}

输出示例：

{
  "ok": true,
  "message_id": 51,
  "status": "sent"
}

规则：

  • 纯文本省略Telegram parse_mode
  • markdown_v2 地图到Telegram MarkdownV2
  • 验证和电报失败返回 {"ok": false, "error": "..." }

tg_send_media

发送照片、文档或音频项目。

示例输入：

{
  "media_type": "photo",
  "source": "/absolute/path/to/image.png",
  "caption": "diagram",
  "reply_to_message_id": null
}

输出示例：

{
  "ok": true,
  "message_id": 52,
  "status": "sent",
  "media_type": "photo"
}

source 可能是：

  • 本地文件路径，作为多部分上传
  • 公共URL
  • 现有的Telegram file_id

tg_report_progress

就地创建或编辑一条进度消息。

示例输入：

{
  "text": "step 2",
  "message_id": 52
}

输出示例：

{
  "ok": true,
  "message_id": 52,
  "action": "edited"
}

图案：

  1. 致电一次 message_id=null
  2. 储存退回的 message_id
  3. 在以后的更新中重用它

tg_request_approval

发送内联键盘批准提示并轮询，直到收到匹配的回拨或超时为止。

示例输入：

{
  "question": "confirm deployment?",
  "options": ["Yes", "No"],
  "offset": 1043,
  "timeout": 120,
  "response_format": "concise"
}

输出示例：

{
  "ok": true,
  "answer": "Yes",
  "message_id": 1048,
  "next_offset": 1051,
  "buffered_messages": []
}

重要合同：

  • 更喜欢 options 作为JSON数组，但逗号分隔的字符串也可用于 使阵列变平的客户端
  • next_offset 当链接审批调用时，应由代理存储
  • 等待时收到的正常聊天消息将返回 buffered_messages
  • 语音信息 buffered_messages 返回为 unsupported
  • 超时返回 "answer": "timeout"
  • response_format="detailed" 还包括 callback_query_id, chosen_option，以及每个缓冲项内的消息元数据

错误样式

工具故障以结构化错误有效载荷的形式返回：

{
  "ok": false,
  "error": "Error: BOT_TOKEN is invalid. Check TELEGRAM_BOT_TOKEN in .env and restart."
}

测试

使用以下命令运行自动化套件：

uv run pytest

此回购包括以下内容：

  • 原始Telegram客户端方法 respx
  • 发送和媒体工具流
  • 缓冲文本、图像、文档和不支持的语音消息的入站规范化
  • 进度创建/编辑行为
  • 审批成功和超时流程

备注

  • 此项目中安装的MCP Python SDK使用传输字符串 streamable-http.
  • 服务器绑定到 127.0.0.1:8000 默认情况下，在以下位置公开MCP端点 /mcp.

相关 MCP