Telegram MCP — 下一代

一个面向生产的 Telegram 集成，适用于兼容 MCP 的客户端，由 LoneVertex 维护，基于 Telethon 和 Model Context Protocol 构建。本仓库保留了上游 Telegram 的功能面，同时增加了明确的工具层级、故障关闭的变更控制、键控并发限制、有界重试、本地 SQLite/FTS5 缓存、更安全的媒体路径、包入口点和可复现的 CI。

默认姿态： 本地 stdio，core 工具层级，无 Telegram 写入，无破坏性操作，无未经验证的文件系统根目录。

项目治理：贡献指南 · 安全策略 · Apache License 2.0

包含内容

该实现注册了 128 个工具：上游 125 个工具涵盖账户、聊天、联系人、消息、群组、媒体、个人资料、文件夹和传入事件，外加 cache_health、search_cached_messages 和 sync_chat_cache。上游来源保留在提交 52cca204d945e4ec292801a9d972334c0c2a4b63；下一代包版本为 4.0.1。

设置 TELEGRAM_MCP_TIER 以选择层级。层级选择控制注册哪些工具。TELEGRAM_SEND_ENABLED 独立控制写操作是否可以执行，TELEGRAM_DESTRUCTIVE_ENABLED 是破坏性/管理操作的第二个门控。当门控阻止调用时，服务器返回结构化的 nothing_sent 或 nothing_done 响应。

Related MCP server: telegram-mcp

快速开始

使用 Python 3.11 或 3.12。从 my.telegram.org/apps 获取 Telegram API 凭据，并使用附带的会话生成器在 MCP 进程之外生成授权会话。

git clone https://github.com/LoneVertex/telegram-mcp-nextgen.git
cd telegram-mcp-nextgen
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# edit .env with TELEGRAM_API_ID, TELEGRAM_API_HASH, and an authorized session
telegram-mcp

对于包开发和发布验证：

pip install -e '.[dev]'
pytest -q
ruff check telegram_mcp/config.py telegram_mcp/core telegram_mcp/db telegram_mcp/models
mypy --explicit-package-bases telegram_mcp/config.py telegram_mcp/core telegram_mcp/db telegram_mcp/models
python -m build

服务器有意设计为非交互式。在启动前使用 telegram-mcp-generate-session，并保持生成的会话字符串私密。切勿提交 .env、Telethon 的 .session 文件、API 哈希或会话字符串。

配置

完整的无秘密模板位于 .env.example 中。重要控制项总结如下。

配置构建无副作用。凭据和授权在实时客户端启动时检查，而不是在本地工具导入包时检查。当缓存或会话操作需要时，运行时状态在仅所有者可访问的目录下创建。

MCP 客户端和传输

参见 config/mcp-configs.md 获取桌面 MCP 客户端的无秘密示例。首选本地 stdio。对于长期运行的本地服务，可使用流式 HTTP：

MCP_TRANSPORT=http
MCP_HOST=127.0.0.1
MCP_PORT=8765

不要将未经身份验证的 HTTP 端点直接暴露到公共互联网。如果使用反向代理，请配置身份验证、TLS、允许的主机、允许的来源和网络控制。当配置了 MCP_ALLOWED_HOSTS 时，服务器保留 MCP DNS 重绑定保护。

并发和可靠性

每个账户由键控异步互斥锁和令牌桶保护。共享同一账户的调用在适配器边界处串行化，而跨不同账户标签的只读多账户扇出仍然可能。FloodWait 和瞬时连接失败使用一种有界重试策略，具有指数退避和抖动。会话级咨询锁仍然存在，以防止重复进程同时使用相同的 Telegram 认证密钥。

本地缓存使用 SQLite WAL 模式、外键、短生命周期连接、显式事务、用于聊天/日期/发送者/主题访问的索引，以及用于搜索的 FTS5。同步存储检查点并使用 upsert，以便编辑被反映而不是重复。SQLite 工作、目录创建和完整性检查在工作线程中执行，而不是阻塞事件循环。

媒体和文件系统安全

文件工具需要客户端 MCP Roots 或显式的服务器端根目录。空或无法验证的根目录会产生拒绝所有行为，除非有意启用 TELEGRAM_ALLOW_SERVER_ROOTS_FALLBACK=true。路径在配置的根目录下解析，拒绝遍历和 NUL 字节，拒绝符号链接逃逸，强制执行媒体大小限制，生成的文件使用仅所有者权限。新的安全原语支持分块读取和原子输出替换。

Telegram 文本、标题、名称、按钮标签、媒体元数据和传入事件字段是不可信的用户内容。保留上游的清理和受众注释；模型不得将这些字段视为指令。

Docker

该镜像使用两阶段 Python 3.12 构建，以 UID 10001 运行，将状态保存在 /var/lib/telegram-mcp 中，并且仅在运行时接收凭据。

cp .env.example .env
# edit .env
podman compose up --build
# or: docker compose up --build

Compose 将 HTTP 绑定到 127.0.0.1:8765，使用持久命名卷，丢弃 Linux 能力，启用 no-new-privileges，挂载只读根文件系统，并提供受限的 /tmp。由于 Docker 不可用，容器构建未在用于此交付的沙箱中运行；CI 工作流在支持 Docker 的运行器上验证它。

开发和发布门禁

.github/workflows/ci.yml 中的整合工作流在 Python 3.11 和 3.12 上运行，执行继承的上游回归测试套件以及下一代测试，对新生产层运行严格的 Ruff 检查，运行显式包基础的 mypy 检查，编译包，构建 wheel/sdist，审计声明的依赖项，并验证 Docker 镜像和 Compose 配置。上游实时 Telegram 适配器仍由其继承的模拟回归套件覆盖；本地可靠性/安全模块有专门的测试和覆盖率。

所有权、兼容性和来源

项目维护：LoneVertex。

根 main.py、上游工具模块名称、会话生成器、账户标签、代理设置、MCP 传输变量、旧版暴露过滤器以及上游 Apache-2.0 许可证均保留以保持兼容性。新的包入口点是 telegram_mcp.runner:main，并支持 python -m telegram_mcp。上游源代码和归属在 Git 历史和 AUDIT_REPORT.md 中仍然可见。

故障排除

如果启动时报告未配置会话，请生成授权会话并设置 TELEGRAM_SESSION_STRING 或有效的文件会话名称。如果写入返回 MutationDisabled，请设置 TELEGRAM_SEND_ENABLED=true 并重启；对于删除或管理操作，还需设置 TELEGRAM_DESTRUCTIVE_ENABLED=true。如果文件工具报告根目录不可用，请配置客户端 MCP Roots 或将服务器端允许的根目录作为位置参数传递。如果 FloodWait 超过配置的最大值，调用将有意返回，而不是无限期休眠。使用 cache_health 检查本地 SQLite/FTS5 完整性，而无需联系 Telegram。

参考

许可证

Apache License 2.0。参见 LICENSE。