mcpField
T
Telegram Bot MCP Server

Telegram Bot MCP Server

本地服务
github.com/cyuanxv通信协作15 天前更新
代码仓库

关于 Telegram Bot MCP Server

这是一个可自托管的 Node.js 服务，通过富文本、媒体和交互按钮操作 Telegram Bot，面向自行配置 Bot 凭据与服务环境的运营者。高级功能须单独配置权限和存储。

主要功能

  1. 01富文本消息
  2. 02媒体操作
  3. 03交互按钮
  4. 04可选队列与收件箱
  5. 05Webhook 支持
  6. 06Rich Messages 与会话

适用场景

  1. 01发送格式化的 Bot 消息
  2. 02处理 Bot 媒体
  3. 03提供交互式消息按钮
  4. 04接收已配置的 webhook 事件

MCP 相关

通过 Streamable HTTP 在 `/api/mcp` 向 MCP 客户端提供 Telegram Bot 操作。服务默认绑定本机回环地址；实际 Bot 操作需要运营者提供 Telegram 凭据。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "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>"
      }
    }
  }
}
启动命令npx -y @cyuanxv/telegram-bot-mcp-server
需要配置的环境变量
MCP_API_KEY密钥Choose a strong local MCP access key. Use the same key in the Authorization header.
TELEGRAM_BOT_TOKEN密钥Your own Telegram Bot token. Required for real Bot operations.
TELEGRAM_CHAT_ID密钥Your own default Telegram chat ID.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
npm@cyuanxv/telegram-bot-mcp-server1.0.1

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Telegram Bot MCP Server

可自托管的 Telegram Bot MCP 服务，支持富文本、媒体和交互式按钮。需要 Node.js 24。此源代码包使用 Streamable HTTP，并绑定到 127.0.0.1；它不是 stdio 服务，也不包含托管服务。

安装 / 安装

将提供的源代码 .tgz 安装到专用目录，不运行生命周期脚本：

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

公开发布后，也可以使用 npx --yes @cyuanxv/[email protected] --port 3000 启动相同版本。此公开软件包命令仅在该版本发布后适用，并且需要下文所述的服务环境。

在服务环境中设置强度足够的 MCP_API_KEY，然后运行 ./node_modules/.bin/telegram-bot-mcp-server --port 3000。首次启动时会在本地构建源代码；后续启动将使用该构建结果。使用 build 子命令重新构建，或使用 start 要求已有构建结果。源代码构建工作区位于 ~/.cache/telegram-bot-mcp-server/；请确保该用户缓存目录可写。依赖项保留在你的 npm 安装目录中。安装钩子不会构建或启动服务。

使用 Authorization: Bearer <your MCP_API_KEY> 连接到 http://127.0.0.1:3000/api/mcp。要执行真实的 Bot 操作，请提供你自己的 TELEGRAM_BOT_TOKEN 和 TELEGRAM_CHAT_ID。不要将令牌放在命令行参数中。若要部署到其他机器，请配置你自己的经过身份验证的 HTTPS 反向代理；云端客户端无法直接连接到本地回环地址。

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

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

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

MCP 密钥授予受信任的操作员访问权限，包括使用原始 chat ID 的工具；已配置的别名并非收件人允许列表。依赖项保留各自的许可证；请参阅 THIRD_PARTY_NOTICES.md。本项目与 Telegram 无关联。

作者与版权 / 作者与版权

© 2026 cyuanxv · X / Twitter @cyuanxv

自有源代码根据 MIT 许可证授权。

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。