mcpField
T
Telegram Bot MCP Server

Telegram Bot MCP Server

Local
github.com/cyuanxvCommunication1Updated 5d ago
Repository

About Telegram Bot MCP Server

A self-hosted Node.js server for operating Telegram bots through rich text, media, and interactive-button capabilities. It is for operators who configure their own bot credentials and service environment; advanced features require explicit configuration and authorization.

Key features

  1. 01Rich text messaging
  2. 02Media operations
  3. 03Interactive buttons
  4. 04Optional queues and inbox
  5. 05Webhook support
  6. 06Rich Messages and sessions

Use cases

  1. 01Sending formatted bot messages
  2. 02Handling bot media
  3. 03Offering interactive message buttons
  4. 04Receiving configured webhook events

MCP support

Exposes Telegram Bot operations to MCP clients over Streamable HTTP at `/api/mcp`. The server binds to localhost by default, and real bot operations require the operator's Telegram credentials.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "cyuanxv-telegram-bot": {
      "command": "npx",
      "args": [
        "-y",
        "@cyuanxv/telegram-bot-mcp-server"
      ],
      "env": {
        "MCP_API_KEY": "<MCP_API_KEY>",
        "TELEGRAM_BOT_TOKEN": "<TELEGRAM_BOT_TOKEN>",
        "TELEGRAM_CHAT_ID": "<TELEGRAM_CHAT_ID>"
      }
    }
  }
}
Run commandnpx -y @cyuanxv/telegram-bot-mcp-server
Environment variables to set
MCP_API_KEYSecretChoose a strong local MCP access key. Use the same key in the Authorization header.
TELEGRAM_BOT_TOKENSecretYour own Telegram Bot token. Required for real Bot operations.
TELEGRAM_CHAT_IDSecretYour own default Telegram chat ID.

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npm@cyuanxv/telegram-bot-mcp-server1.0.1

Tools

No tool list yet

Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.

Details

From the project 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:

npm install --ignore-scripts /absolute/path/to/cyuanxv-telegram-bot-mcp-server-1.0.0.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.

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.