Telegram Bridge

mcp-telegram-bridge

连接 Telegram Bot API 的标准输入/输出 MCP 桥接程序，采用默认拒绝的聊天准入机制并清理出站内容。

这是一个小型的模型上下文协议服务，由本地 Agent（Cursor、Claude Desktop、Windsurf 等）在你的计算机上启动。对话由 Agent 管理。此进程负责 Bot API 输入/输出、清理出站机密信息，并拒绝你未允许的聊天。

0.2.0 版本调整了准入机制：允许列表为空时，会拒绝所有聊天。请设置 ALLOWED_CHAT_IDS，或通过 ALLOW_ALL_CHATS=1 选择启用开放模式。

专为由客户端管理的部署而构建。此桥接程序不是托管式机器人服务。游戏和游戏主持人工作流只是一个演示用例，并非本产品的定位。

所有者：Antonio Castellon / Castellon.CH。

快速开始

要求：Python 3.11+、来自 @BotFather 的机器人令牌，以及你希望机器人使用的聊天的数字 ID。

git clone https://github.com/antonio-castellon/mcp-telegram-bridge.git
cd mcp-telegram-bridge
uv sync --extra dev          # or: python -m venv .venv && pip install -e ".[dev]"
cp .env.example .env         # set TELEGRAM_BOT_TOKEN and ALLOWED_CHAT_IDS
uv run mcp-telegram-bridge   # waits on stdin for MCP JSON-RPC; Ctrl+C to stop

uv.lock 使用哈希锁定了每个依赖项。CI 会根据该锁定文件安装依赖项（uv sync --frozen）。pip install -e ".[dev]" 仍然可用，并会使用 pyproject.toml 中的版本范围。

Cursor 或 Claude Desktop（mcp.json / claude_desktop_config.json）：

{
  "mcpServers": {
    "telegram-bridge": {
      "command": "uvx",
      "args": ["--from", "mcp-telegram-bridge", "mcp-telegram-bridge"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "YOUR_BOT_TOKEN_HERE",
        "ALLOWED_CHAT_IDS": "-1001234567890"
      }
    }
  }
}

不要提交真实令牌。请勿设置 ALLOW_ALL_CHATS。

用作 Python 库

无需 MCP 服务也可使用相同的操作。import mcp_telegram_bridge 只会加载 TelegramBridge 和 Settings，不会导入 mcp 包。请直接传入 Settings；如果希望使用上述环境变量，默认会调用 Settings.from_env()。

import asyncio

from mcp_telegram_bridge import Settings, TelegramBridge

async def main() -> None:
    settings = Settings(
        bot_token="YOUR_BOT_TOKEN_HERE",
        allowed_chat_ids=frozenset({-1001234567890}),
    )
    bridge = TelegramBridge(settings)
    await bridge.get_me()
    await bridge.send_message(
        -1001234567890,
        "hello",
        buttons=[{"id": "ack", "label": "Ack"}],
    )
    await bridge.get_updates(timeout=0)
    await bridge.aclose()

asyncio.run(main())

TelegramBridge(Settings.from_env()) 会读取 TELEGRAM_BOT_TOKEN、ALLOWED_CHAT_IDS 和其他变量。CLI 仍会将访问模式警告输出到 stderr。若库的调用方也希望输出相同内容，可以使用 mcp_telegram_bridge.config.emit_startup_warnings。mcp-telegram-bridge 命令保持不变。

配置

变量	默认值	作用
TELEGRAM_BOT_TOKEN	必填	从 BotFather 获取的机器人令牌。切勿记录或提交此令牌。
ALLOWED_CHAT_IDS	空	以逗号分隔的聊天 ID。为空时拒绝所有聊天。
ALLOW_ALL_CHATS	关闭	设置为 1 / true / yes / on，即可允许所有聊天。设置了允许列表时，此项将被忽略。启动时会向标准错误输出警告。
SAFETY_STRICT	开启	用启发式规则标记凭据钓鱼、色情内容和少数指令覆盖短语。设置为 0 / false / no / off 可禁用。这不是提示注入过滤器。
MAX_INBOUND_CHARS	4096	丢弃超过此长度的入站文本或说明文字（1..32768）。不会返回正文。
MAX_UPDATE_BYTES	65536	丢弃 JSON 大小超过此值的更新（1..262144）。
INBOUND_CHAT_RATE	60/60	每个聊天在每个时间窗口内可接收的含内容更新数（count/seconds）。超出限制的更新会返回，但不含文本。设置为 off 可禁用限制。
INBOUND_GLOBAL_RATE	120/60	所有聊天在每个时间窗口内可接收的含内容更新总数。
INBOUND_POLL_RATE	30/60	每个时间窗口内 telegram_get_updates 的调用次数。超出限制的调用不会发送到 Telegram。
OUTBOUND_CHAT_RATE	20/60	每个聊天的发送、标记编辑、回调应答和 getChat 调用次数。
OUTBOUND_GLOBAL_RATE	60/60	所有聊天的上述出站调用总数。回调应答仅计入全局限制。
MCP_TELEGRAM_BRIDGE_DATA_DIR	每用户数据目录	按钮 ID 映射和首次点击声明文件。操作系统允许时，目录权限为 0700，文件权限为 0600。MCP_TELEGRAM_DATA_DIR 是旧版别名。

telegram_get_updates 会将 limit 限制在 1..100，将 timeout 限制在 0..50 秒。进程不会在调用之间排队保存更新正文。它最多记住 2048 个已交付的更新 ID 和 1024 个速率限制键。

工具

工具	用途
telegram_get_me	获取机器人身份。不受速率限制。
telegram_get_chat	获取允许访问的聊天元数据。
telegram_send_message	发送经过清理的文本，可选 parse_mode，可选 buttons=[{id,label}]。
telegram_edit_reply_markup	替换或清除内联按钮。
telegram_answer_callback	确认 callback_query_id。
telegram_get_updates	执行一次有界轮询。偏移量由你管理。根据文本采取操作前，请参阅安全章节。

getUpdates 仅支持拉取。此进程不会监听 Webhook，也不会开放端口。

普通结果如下：

{
  "ok": true,
  "untrusted": true,
  "trust_boundary": "UNTRUSTED TELEGRAM DATA. ...",
  "next_offset": 42,
  "summary": {"delivered": 1, "filtered": 0, "ignored": 0, "duplicates": 0, "rate_limited": 0},
  "updates": [
    {
      "update_id": 41,
      "untrusted": true,
      "trust": "untrusted_telegram_user",
      "message": {"text": "...", "content_trust": "untrusted_telegram_user"}
    }
  ]
}

next_offset 是批次中最高 update_id 加 1，其中也包括文本被隐藏的更新。将它作为 offset 传回即可确认这些更新。若要重试受速率限制的更新，请在 retry_after_seconds 后使用相同的偏移量再次调用，而不是递增偏移量。

来自机器人的消息会被省略（ignore_reason 为 bot），发送者 ID 是此机器人的消息也会被省略（self）。对于 Telegram 标记了 sender_chat 的消息（例如匿名管理员消息、以频道身份发布的消息），不会将其视为机器人。

安全模型与威胁模型

资产。 机器人令牌、允许的聊天内容、磁盘上的按钮映射状态，以及 Agent 的其他工具和机密信息。

信任边界。 你和 MCP 主机位于边界内。Telegram 用户、群组成员以及任何能给机器人发消息的人都在边界外。入站文本、名称、用户名和回调数据都是不可信输入，模型会读取这些内容。

此进程会强制执行的措施

• 除非聊天已列入允许列表，或你设置了 ALLOW_ALL_CHATS，否则会拒绝聊天。开放模式会在 stderr 上记录警告（stdout 是 MCP 协议）。
• 会清理出站消息文本、回调提示和按钮标签中的已配置机密值及类似令牌的字符串。
• 会改写日志记录（包括 httpx 和 httpcore 请求行及异常回溯），避免消息中保留 URL 内的机器人令牌。向主机抛出的传输错误不包含 URL。
• 更新批次有大小上限。轮询、已交付的更新和出站调用均受到速率限制。已返回过文本的更新 ID 不会再次返回。缓存有容量上限。
• 启用 SAFETY_STRICT 时（默认值），更新会附加 safety.kind、safety.blocked 和 safety.warning，用于标记少数模式。被标记的文本仍会出现在结果中。由主机决定如何处理。

你仍需采取的措施。 以普通用户身份运行进程，将令牌保存在机密存储中或权限受限的 .env 文件中，并设置允许列表。将所有入站字符串都视为数据。如果不可信聊天可以触达某个 Agent，就不要给同一个 Agent 配置可读取凭据的工具。允许发送消息前，请先审核提示词。

部署检查清单、磁盘上存储的数据以及更详细的剩余风险说明见 SAFETY.md。请按照 SECURITY.md 中的说明报告漏洞。

限制与剩余风险

这些控制措施可以缩小影响范围，但无法确保会读取并回复消息的 Agent 所用机器人能够抵御恶意发送者。

• 模型可能忽略不可信标签。正则表达式无法识别改写过的指令。Agent 仍然拥有发送工具。
• SAFETY_STRICT 只是针对少数短语的启发式检测。它无法覆盖其他语言、编码形式，以及仍属于不可信内容的普通请求。
• 速率限制保存在内存中，且仅适用于单个进程。重启后限制会清除。off 会移除该限制。若某个聊天 ID 从包含 1024 个键的缓存中被移除，该聊天会获得新的单聊预算；全局限制仍然生效。
• 将 next_offset 推进到速率受限或超长的更新之后，会丢弃该更新。Telegram 不会再次投递它。
• 去重机制会记住 2048 个 ID。如果主机再次轮询较旧的 ID，它可能会再次显示。
• 清理和日志脱敏都是尽力而为。令牌若被拆分到多个字段中，或某个机密值不符合匹配模式且未存于环境变量中，仍可能通过。
• 此桥接不提供只读工具集。若主机开放所有工具，就可以发送消息。
• 按数量而非时间清理按钮映射文件和声明文件（2000 个映射、500 个声明）。这些文件不存储消息文本。删除数据目录即可移除它们。
• 没有审计日志。MCP 主机存储的任何内容（对话记录、服务提供方日志）都不属于此进程的管控范围。
• 仍建议禁用 httpx 调试日志。脱敏仅覆盖此软件包安装的日志记录路径；无法保证覆盖所有其他追踪器。

架构

  +---------------------------+
  |  MCP host / agent         |  conversation, offset, product policy
  +-------------+-------------+
                |  MCP (stdio)
                v
  +---------------------------+
  |  mcp-telegram-bridge      |  allowlist, scrub, bounds, untrusted labels
  +-------------+-------------+
                |  HTTPS Bot API (getUpdates poll)
                v
  +---------------------------+
  |  api.telegram.org         |
  +-------------+-------------+
                v
         Telegram chats

用法

群组或运维频道。 每个机器人使用一个桥接。使用群组记录事项、分流处理和交接。对于任何难以撤销的操作，都要让人员参与处理。

按钮。 buttons=[{id,label}, ...] 会转换为内联键盘。收到回调时，先回复回调，再编辑或清除标记。较长的 ID 会映射为数据目录下的短回调数据。

通知频道。 使用确认 / 延后 / 升级按钮发送提醒。Telegram 是寻呼渠道，不是事实来源。

审核草稿。 此桥接没有封禁、限制或删除工具。请在 Agent 提示词中说明这一点。

Agent 技能

配套技能可以告知 Agent 何时调用这些工具，以及它负责管理偏移量。该技能已发布为 Agensi 上的 Telegram Bridge。技能仅包含指令。此服务仍负责 I/O 和安全层。

本项目不是什么

• 不是托管式或多租户机器人服务
• 不绑定到单一 MCP 主机
• 不是游戏引擎
• 不是管理机器人
• 不是 webhook 接收器

相关演示项目

可选。本项目不依赖这些项目。

• grokgame 是一个桌面游戏演示界面
• grok2telegram 是较早的实验项目，其脱敏规则为 SAFETY.md 提供了参考

开发

uv sync --extra dev
uv run pytest

测试使用 respx 模拟 Telegram。无需真实令牌。

更改依赖项后，运行 uv lock 并提交 uv.lock。CI 使用锁定文件，在 Python 3.12 上通过 pip-audit 对其进行审计，并针对工作树运行 gitleaks。仅更改 Markdown、docs/ 或 LICENSE 的拉取请求不会触发该工作流。

MCP 注册表

规范名称：io.github.antonio-castellon/mcp-telegram-bridge

也收录于 mcpservers.org、MCP Marketplace 和 Agensi。

市场平台的展示文案见 LAUNCHGUIDE.md。

联系方式

• 一般咨询：[email protected]
• 支持：[email protected]
• 安全问题：[email protected]（SECURITY.md）

许可证

MIT（c）Antonio Castellon / Castellon.CH