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 分