AI导哈

Telegram机器人MCP服务

Telegram Bot API MCP服务器，支持基于工作区的消息路由，适用于跨频道消息传递和通知。

  • by aviman1109
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 aviman1109/telegram_mcp

使用说明

电报MCP

Telegram Bot API MCP服务器，具有针对 模型上下文协议.

特性

  • 通知 --发送到工作区的默认通道（通过中的HTTP标头路由 .mcp.json)
  • send_message --发送到任何特定的聊天/话题（用于跨渠道传递）
  • get_bot_info --检索机器人身份和功能
  • 每个工作区的默认路由通过 X-Default-Chat-Id 和 X-Default-Topic-Id 标头
  • 支持 Markdown, MarkdownV2，以及 HTML 解析模式

需求

  • Python 3.11+
  • 来自的Telegram Bot令牌 @植物学家
  • 必须将机器人添加到具有发送消息权限的目标组中

配置

环境变量

变量 必填 描述
TELEGRAM_BOT_TOKEN 是 BotFather的Bot API令牌
PORT 无 服务器端口（默认值： 38094)
MCP_TRANSPORT 没有 http （默认）， sse，或 stdio
MCP_HOST 否 绑定地址（默认值： 0.0.0.0)
MCP_PATH 无 MCP端点路径（默认值： /mcp)
MCP_ALLOWED_HOSTS 否 允许使用逗号分隔的主机
MCP_ALLOWED_ORIGINS 否 允许使用逗号分隔的起源

按工作区路由

每个工作区的 .mcp.json 可以包含设置默认Telegram目标的HTTP标头 notify():

{
  "mcpServers": {
    "telegram": {
      "type": "http",
      "url": "http://127.0.0.1:38094/mcp",
      "headers": {
        "X-Default-Chat-Id": "-1003728321833",
        "X-Default-Topic-Id": "3"
      }
    }
  }
}
标题 描述
X-Default-Chat-Id 默认Telegram聊天ID（需要 notify)
X-Default-Topic-Id 默认值 message_thread_id 主题路由（常规主题省略）

已知聊天ID

chat_id 名称 使用
8209401698 卡斯珀DM(@aviman1109 ↔ @casper_nexus_bot) 训练/比赛现场推送 --iOS Siri大声朗读DM；主题消息不广播
-1003728321833 指揮中心 组 平台/多主题路由（见上文主题3-6）

DM要求用户 /start 首先是机器人。

用法

Docker Compose

docker compose up -d telegram-mcp

独立

pip install .
TELEGRAM_BOT_TOKEN=<token> telegram-mcp

工具

通知

向此工作区的默认频道发送消息。无需指定 chat_id 或 topic_id --它们来自中配置的HTTP标头 .mcp.json.

参数 类型 必填 说明
text str 是 消息内容
parse_mode str 没有 Markdown, MarkdownV2，或 HTML
disable_notification bool 否 静默发送

如果未配置默认标头，则返回错误。

send_message

向任何特定聊天或主题发送消息。用于跨渠道交付。

参数 类型 必填 说明
chat_id int 是 电报聊天ID（群组为负）
text str 是 消息内容
topic_id int 没有 message_thread_id 用于论坛主题传递
parse_mode str 没有 Markdown, MarkdownV2，或 HTML
disable_notification bool 否 静默发送

注： Telegram General主题不接受 message_thread_id.省略 topic_id 邮寄给将军。

get_bot_info

返回机器人身份：id、用户名、名称和功能。

秘密

将机器人令牌存储在 .env 通过您的秘密管理器进行文件或注入：

TELEGRAM_BOT_TOKEN=your_token_here

项目结构

telegram_mcp/
├── Dockerfile
├── pyproject.toml
├── README.md
├── src/telegram_mcp/
│   ├── __init__.py
│   ├── __main__.py
│   ├── server.py       # MCP server bootstrap + header extraction middleware
│   ├── config.py       # Environment-based configuration
│   ├── client.py       # Telegram Bot API async client
│   ├── defaults.py     # Per-request routing via contextvars
│   └── tools.py        # MCP tool definitions (notify, send_message, get_bot_info)
└── secrets/
    └── telegram.env.tpl  # 1Password template

许可证

麻省理工学院

相关 MCP