Telegram Bot MCP Server

io.github.cyuanxvPublished by GitHub account cyuanxvv1.0.1Updated Oct 25, 2026

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

VerifiedSTDIODesktop onlyProductivity & WorkflowCommunication & Collaboration

Overview

AI-generated overview

Self-hosted Telegram Bot MCP server that lets an assistant send rich text, media and interactive buttons through your own bot.

What you can do
Send rich text messages, media and interactive buttons through your own Telegram bot, with a default chat alias for basic sends and Rich sessions for private chats with explicit target authorization. Run a local Streamable HTTP service on loopback that an MCP client connects to with a bearer key. Optionally enable advanced features such as queues, inbox, media byte uploads, callbacks, Rich Messages and personal accounts by configuring permissions, target scope and storage. Rebuild or start the local build through subcommands.
When to use it
Use it when you want an AI assistant to post formatted Telegram messages, media or button-based interactions from a bot you control, and you are willing to self-host the service on your own machine or behind your own HTTPS proxy.
Requirements
Node.js 24. Local npm package installed from a source archive or launched with npx once published; the service binds to 127.0.0.1 and is reached at its local MCP endpoint. A strong MCP_API_KEY set in the environment and sent as an Authorization bearer header, plus your own TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID. A writable user cache directory for the build workspace. For remote use, your own authenticated HTTPS reverse proxy and TELEGRAM_PUBLIC_ORIGIN.
Before you install
The MCP key grants trusted operator access, including tools that accept raw chat IDs, and configured aliases are not a recipient allowlist. The bot token and chat ID are secrets; do not put tokens in command-line arguments. Advanced features are off by default and need permissions, target scope and storage configured first; review the SQL migrations and runtime grants separately and do not give migration admin credentials to the running service. Without TELEGRAM_PUBLIC_ORIGIN set to your own HTT

Installation

In SourceWeft

  1. Open Telegram Bot MCP Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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.

Source: server/README.md at commit 165a098

Tools

0
SourceWeft started this package once in an isolated sandbox, without credentials, to list its tools. That failed: the package type cannot run in the sandbox.

Version history

2
  1. v1.0.1LatestOct 25, 2026
  2. v1.0.0Oct 22, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts