AI导哈

Telegram MCP服务器

Telegram MCP服务器是一个生产级的Telegram多协议集成服务器，支持Bot API和MTProto协议，提供安全、高效的消息和媒体管理功能。

  • by mhbdev
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 mhbdev/telegram-mcp

使用说明

电报mcp

生产级Telegram MCP服务器（Bot API完整域+MTProto基金会）。

特性

  • 双重运输： stdio 以及可流式传输的HTTP(/mcp).
  • 安全默认设置：OIDC JWT身份验证（Keycloak）、RBAC+工具分配列表、静态加密的bot/MTProto凭据。
  • 从生成的严格的每种方法Bot API JSON架构验证 @grammyjs/types.
  • 自动Bot API对生成的方法库存进行奇偶校验。
  • PostgreSQL持久性，具有幂等性、审计日志、策略存储和会话/帐户记录。
  • Telegram工具系列：
    • telegram.bot.messages
    • telegram.bot.media
    • telegram.bot.chats
    • telegram.bot.members
    • telegram.bot.inline
    • telegram.bot.commands
    • telegram.bot.webhooks
    • telegram.bot.payments
    • telegram.bot.business
    • telegram.bot.passport
    • telegram.bot.stickers
    • telegram.bot.forum
    • telegram.bot.raw （受限）
    • telegram.mtproto.sessions
    • telegram.mtproto.core
  • MTProto超集工具系列版本：
    • telegram.v2.chats
    • telegram.v2.messages
    • telegram.v2.contacts
    • telegram.v2.profile
    • telegram.v2.search
    • telegram.v2.privacy
    • telegram.v2.drafts
    • telegram.v2.inline
    • telegram.v2.media （S3/MinIO电桥）
    • telegram.v2.approval.request
    • telegram.v2.approval.execute
    • telegram.v2.approval.status
  • MCP资源：
    • telegram://bots
    • telegram://bot/{botId}/profile
    • telegram://policies
    • telegram://audit/recent
    • telegram://v2/chats
    • telegram://v2/contacts
    • telegram://v2/drafts
    • telegram://v2/approvals/recent
    • telegram://v2/media/{objectId}

先决条件

  • Node.js 22+
  • Docker+Docker Compose（适用于 --profile local)
  • PostgreSQL 16+（适用于 --profile external)
  • Telegram机器人令牌
  • 电报 apiId 和 apiHash MTProto

快速启动（无克隆）

单线设置：

npx @mhbdev/telegram-mcp@latest setup

单行运行时（自愈）：

npx @mhbdev/telegram-mcp@latest run

直接服务模式：

npx @mhbdev/telegram-mcp@latest serve --transport=stdio

档案

  • local （默认）：写入 .telegram-mcp/config.json 和 .telegram-mcp/.env，套 auth.required=false，开始 postgres + keycloak + minio + minio-init，并运行迁移，除非 --skip-migrate.
  • external：默认情况下仅写入config/env，不引导本地依赖关系。

配置和环境默认值

  • 配置发现顺序：
    • .telegram-mcp/config.json
    • .telegram-mcp/config.yaml
    • .telegram-mcp/config.yml
    • telegram-mcp.config.json
    • telegram-mcp.config.example.json
  • 默认生成的文件：
    • .telegram-mcp/config.json
    • .telegram-mcp/.env
  • 安装格式：
    • 默认 json
    • --format yaml 支持

示例：

npx @mhbdev/telegram-mcp@latest setup --format yaml
npx @mhbdev/telegram-mcp@latest setup --profile external --non-interactive --yes
npx @mhbdev/telegram-mcp@latest run --transport http --host 127.0.0.1 --port 3000 --non-interactive --yes

命令行界面

  • telegram-mcp setup [--profile local|external] [--format json|yaml]
  • telegram-mcp run [--profile local|external] [--transport stdio|http]
  • telegram-mcp serve --transport=stdio
  • telegram-mcp serve --transport=http --port=3000
  • telegram-mcp migrate
  • telegram-mcp policy validate --file=policy.json
  • telegram-mcp bot account-upsert --account-ref=... --display-name=... --token=...
  • telegram-mcp bot webhook set --account-ref=... --url=...
  • telegram-mcp mtproto session add --account-ref=... --display-name=... --phone=...
  • telegram-mcp mtproto session list
  • telegram-mcp mtproto session revoke --account-ref=...
  • telegram-mcp mtproto session health --account-ref=...

HTTP端点

  • POST|GET|DELETE /mcp
  • GET /healthz
  • GET /readyz
  • GET /metrics

Docker Compose（Postgres+Keycloak+MinIO+应用程序）

cd docker
TELEGRAM_MCP_MASTER_KEY="$(openssl rand -base64 32)" docker compose up --build

竞争矩阵

  • docs/competitor-gap-matrix.md 将竞争对手能力组映射到 telegram.v2 操作。

测试

npm run test

CLI端到端烟雾测试：

npm run build
npm run test:e2e:smoke

可选全栈e2e（手动/夜间风格）：

npm run build
npm run test:e2e:fullstack

重新生成并验证Bot API合同：

npm run generate:bot-contract
npm run check:bot-contract

GitHub自动化：

  • .github/workflows/bot-contract-sync.yml 在以下情况下重新生成合同工件 @grammyjs/types 凸起（过孔 package*.json 更改上 main)并在生成的文件发生变化时打开自动PR。
  • .github/workflows/e2e-fullstack.yml 按计划/手动触发器运行可选的全栈CLI e2e。

故障排除

  • Docker Compose丢失 setup --profile local:
    • 交互模式提供回退选项
    • 非交互模式在没有依赖引导的情况下继续安装
  • 非交互式 run 缺少设置工件：
    • 通过 --yes 因此，自愈设置可以自动运行
  • 现有的配置/env文件：
    • 在交互模式下覆盖之前的设置提示
    • 非交互式覆盖需要 --force

制作笔记

  • 保持 TELEGRAM_MCP_MASTER_KEY 在秘密管理器或密封环境中保密。
  • 旋转 TELEGRAM_MCP_PREVIOUS_MASTER_KEY 用于零停机解密回退。
  • 保持 telegram.bot.raw 限于 admin/owner.
  • 默认情况下仅使用元数据保留；除非需要，否则避免存储消息有效载荷。

相关 MCP