Telegram Bot MCP Server

io.github.cyuanxv由 GitHub 账号 cyuanxv 发布v1.0.1更新于 Oct 25, 2026

Self-hosted Telegram Bot MCP server for rich text, media and interactive buttons.

已验证STDIO仅桌面效率与工作流沟通与协作

概览

AI 生成的概览

自托管的 Telegram Bot MCP 服务器，让助手通过你自己的机器人发送富文本、媒体和交互按钮。

可以做什么
通过你自己的 Telegram 机器人发送富文本消息、媒体和交互按钮，基础发送使用默认聊天别名，私聊需使用 Rich 会话并显式授权目标。在本机回环地址运行 Streamable HTTP 服务，MCP 客户端用 Bearer 密钥连接。可选启用队列、收件箱、媒体字节上传、回调、Rich Messages 和个人账号等高级功能，需先配置权限、目标范围和存储。通过子命令重建或启动本地构建。
适用场景
当你希望 AI 助手从自己控制的机器人向 Telegram 发送格式化消息、媒体或按钮交互，并愿意自行在本机或自有 HTTPS 反向代理后托管该服务时使用。
运行要求
需要 Node.js 24。从源码包本地安装 npm 包，或在该版本发布后用 npx 启动；服务绑定 127.0.0.1，通过本地 MCP 端点访问。需在环境中设置强 MCP_API_KEY 并作为 Authorization Bearer 头发送，还需自备 TELEGRAM_BOT_TOKEN 和 TELEGRAM_CHAT_ID。构建工作区需要可写的用户缓存目录。远程使用需自备带认证的 HTTPS 反向代理并设置 TELEGRAM_PUBLIC_ORIGIN。
安装前请注意
MCP 密钥授予受信任的操作员权限，包括接受原始聊天 ID 的工具，已配置的别名并不是收件人白名单。机器人令牌和聊天 ID 属于机密，不要把令牌放进命令行参数。高级功能默认关闭，需先配置权限、目标范围和存储；SQL 迁移和运行时授权需单独审阅，不要把迁移管理员凭据交给运行中的服务。未将 TELEGRAM_PUBLIC_ORIGIN 设为你自己的 HTTPS 地址时，无法接收真实事件。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Telegram Bot MCP Server，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

Telegram Bot MCP Server

Self-hosted Telegram Bot MCP server for rich text, media and interactive buttons. Node.js 24 is required. This source package uses Streamable HTTP and binds to 127.0.0.1; it is not a stdio server and includes no hosted service.

Installation / 安装

Install a supplied source .tgz into a dedicated directory, without lifecycle scripts:

sh
npm install --ignore-scripts /absolute/path/to/cyuanxv-telegram-bot-mcp-server-1.0.1.tgz

After public publication, the same version can also be launched with npx --yes @cyuanxv/[email protected] --port 3000. This public-package command applies only once that version has been published, and requires the service environment described below.

Set a strong MCP_API_KEY in your service environment and run ./node_modules/.bin/telegram-bot-mcp-server --port 3000. The first launch builds the source locally; subsequent launches use that build. Use the build subcommand to rebuild, or start to require an existing build. The source build workspace is under ~/.cache/telegram-bot-mcp-server/; keep that user cache writable. Dependencies remain in your npm installation. No install hook builds or starts the service.

Connect to http://127.0.0.1:3000/api/mcp using Authorization: Bearer <your MCP_API_KEY>. Provide your own TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID for real Bot operations. Do not put tokens in command-line arguments. For deployment on another machine, configure your own authenticated HTTPS reverse proxy; cloud clients cannot connect directly to your local loopback address.

默认情况下，队列、收件箱、媒体字节上传、回调、Rich Messages、个人账号等高级功能不会自动启用。启用前配置对应权限、目标范围和存储。migrations/ 是按功能分组的 SQL，runtime 示例授权需单独审阅；不要把迁移管理员凭据交给运行服务。

TELEGRAM_PUBLIC_ORIGIN 必须设为你自己的 HTTPS 服务根地址，供 webhook 归属校验与注册使用。不配置时为 .invalid 占位地址，无法接收真实事件。

demo-group 是替换私人配置的兼容别名，不代表真实群；基础默认 chat 会映射到此别名。当前直接 Rich 发送仅开放 default Bot / demo-group，私聊需使用 Rich session 和显式目标授权。不会自动注册 webhook、导入账号或发送消息。

The MCP key grants trusted operator access, including tools that accept raw chat IDs; configured aliases are not a recipient allowlist. Dependencies retain their own licenses; see THIRD_PARTY_NOTICES.md. This project is not affiliated with Telegram.

Author and copyright / 作者与版权

© 2026 cyuanxv · X / Twitter @cyuanxv

Own source code is licensed under MIT.

来源：server/README.md，提交 165a098

工具

0
SourceWeft 曾在隔离沙箱中以无凭据方式启动该软件包一次，以列出其工具，但未能完成：该软件包类型无法在沙箱中运行。

版本历史

2
  1. v1.0.1最新Oct 25, 2026
  2. v1.0.0Oct 22, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分