TG multi-account MCP

TG 多账号 MCP

俄语文档

一个可自托管的 Model Context Protocol 服务，让 AI Agent 通过明确选定的用户账号和可选机器人使用 Telegram。账号通过本地网页向导连接：扫描 QR 码，并在需要时输入 Telegram 两步验证密码。

该服务面向 Agent 工具场景，而非 Telegram 客户端。它可以搜索聊天记录、读取文件夹和话题、下载附件、跟踪更新、创建草稿和发送消息。每项操作都会指定所用的账号或机器人；服务绝不会擅自选择发送方。

重要

Telegram 会话可以访问相应账号。请在你控制的基础设施上运行此服务，保护状态目录和 MCP 令牌，并仅向 Agent 令牌授予所需权限。

这是一个使用 Telegram API 的非官方集成，与 Telegram 无关，也未获 Telegram 认可。

支持的功能

• 支持多个 Telegram 用户账号，每个账号都有独立的 QR 码／两步验证接入流程和会话。
• 可在控制面板中停用、重新连接或永久删除账号及其本地会话。
• 可通过 BotFather 令牌独立连接 Telegram 机器人。
• 支持采用 Bearer 令牌身份验证的 Streamable HTTP MCP。
• 提供聊天、文件夹、消息、附件、提及、话题、回复线程和全局搜索工具。
• 查找聊天时支持西里尔字母／拉丁字母转写匹配。
• 支持用户和机器人发送消息、编辑、定时发送、转发、添加反应、创建草稿及使用幂等键。
• 提供带有 read、send 和 admin 权限的 Agent 令牌，并支持身份／聊天允许列表。
• 私有运维控制面板会记录元数据，但不记录消息文本、查询、密码或令牌。
• 持续进行本地语义索引和项目记忆，并支持配置嵌入提供方。
• 文本 RAG 和 S3 附件规则相互独立，支持群组／频道默认规则和按聊天单独设置。
• 监控队列速度、积压和预计时间，并提供可搜索、可筛选、可分页的聊天表格。
• 支持通过 Docker Compose 部署，并由 Caddy 管理 HTTPS。

请参阅工具目录，了解 MCP 工具及其行为说明，其中包括项目记忆和本地归档。

控制面板预览

以下是运行中控制面板的浏览器截图，使用的均为虚构账号、聊天、标识符和统计数据。其中不包含真实 Telegram 消息或部署密钥；数字仅用于展示界面，并非实测性能数据。

默认存储规则与按聊天设置的规则分开管理：

移动端视图 · 移动端规则编辑器

要求

• Python 3.12+
• uv
• 从 my.telegram.org 获取的 Telegram api_id 和 api_hash

仅 Compose 部署需要 Docker 和域名。

快速开始

安装已发布的软件包：

uv tool install tg-account-mcp
tg-mcp setup
TG_MCP_PORT=8765 tg-mcp serve

从源代码检出版本进行开发：

uv sync --frozen
uv run tg-mcp setup
TG_MCP_PORT=8765 uv run tg-mcp serve

setup 会通过本地终端输入请求 Telegram API 凭据，并生成随机 MCP 访问令牌。它不会请求你的电话号码或账户密码。

打开 http://127.0.0.1:8765/ 并按照账户向导操作：

1. 在 Telegram → 设置 → 设备 → 关联桌面设备 中扫描二维码。
2. 如果启用了双重验证（2FA），请输入 Telegram 云密码。
3. 为账户设置本地显示名称。

重复运行向导即可添加更多账户。机器人为可选项，需在仪表板中单独添加。存储之前，系统会使用 Telegram 验证其令牌。

状态目录默认为 ~/.local/share/tg-mcp。可通过 --state-dir 或 TG_MCP_STATE_DIR 覆盖。

连接 MCP 客户端

在本地打印主令牌：

uv run tg-mcp show-token

将客户端配置为使用 Streamable HTTP 端点和 Bearer 请求头：

{
  "url": "http://127.0.0.1:8765/mcp",
  "headers": {
    "Authorization": "Bearer <MCP_TOKEN>"
  }
}

具体配置结构取决于 MCP 客户端。目前不支持要求使用 OAuth 且无法设置 Bearer 请求头的客户端。

请从 get_capabilities、list_accounts 和 list_bots 开始。所有账户和机器人操作都需要明确的稳定 ID，例如 acct_… 或 bot_…。

对于“显示 ITQ 中今天与我的任务相关的消息”这类按文件夹筛选的请求，Agent 可以调用 list_folders，然后使用匹配的 date_from 和 date_to 值以及 Europe/Madrid 这类 IANA 时区调用 get_folder_messages，前提是根据下文的同意要求，获准处理这些内容。

Codex 插件

此仓库还提供一个 Codex 插件，支持经过身份验证的自动服务发现，以及用于聊天解析、文件夹摘要、完整分页、附件、草稿和幂等发送的工作流技能。

codex plugin marketplace add Mesteriis/tg-account-mcp --ref main
codex plugin add tg-account-mcp@tg-account-mcp

该插件会向本地计算机和网络发送经过身份验证的发现请求。发现请求和回复均使用配置的 MCP 令牌进行身份验证；令牌本身绝不会被广播，也不会在已发现的端点通过身份验证之前发送。设置 TG_MCP_URL 可跳过发现并使用指定的 HTTPS 端点。有关服务设置和提示词示例，请参阅 Codex 插件指南。

当 Codex 和服务以同一 OS 用户身份在同一台计算机上运行时，桥接程序会自动从受保护的本地状态中读取令牌。对于运行在另一台计算机上的服务，请将 TG_MCP_TOKEN 提供给 Codex 进程。

负责任地使用并遵守 Telegram 条款

运营者必须遵守 Telegram API 条款和内容许可条款。具体而言：

• 获取并使用你自己的 Telegram api_id；
• 未经用户知情并同意，不得代表用户执行操作；
• 除非每位相关用户都已针对特定内容和上下文给予明确、知情、肯定且持续有效的同意，否则不得抓取、索引、收集、汇总 Telegram 内容，不得使用 Telegram 内容训练或评测，也不得以其他方式将 Telegram 内容提供给 AI/ML 系统；
• 尊重其消息或文件被访问的人员的权利、隐私和指示。

安装本软件并不意味着你获得了 Telegram 内容的使用权。请使用合成数据、你自己保存的消息，或已取得所需同意且同意仍然有效的聊天内容。

Agent 访问控制

setup 生成的令牌是管理令牌。使用 create_agent_token 为每个 Agent 单独签发令牌，并按以下条件限制权限：

• 范围：read、send 或 admin；
• 允许访问的账户和机器人 ID；
• 允许访问的聊天 ID。

系统仅保留 Agent 令牌的 SHA-256 哈希值，明文令牌只会返回一次。使用 revoke_agent_token 撤销访问权限。受聊天 ID 限制的令牌无法使用汇总收件箱、文件夹或全局搜索工具，因为这些操作可能会暴露相邻聊天的内容。

直接 LAN 部署

若要在不使用 Compose HTTPS 代理的可信专用网络中部署，请将服务绑定到 LAN 地址， 并在 LAN 上启动：

TG_MCP_BIND=0.0.0.0 \
TG_MCP_PORT=8765 \
TG_MCP_TRUSTED_NETWORKS=192.168.1.0/24 \
tg-mcp serve

TG_MCP_TRUSTED_NETWORKS 是可选项，默认值为空。设为专用 CIDR 网段后，直接 TCP 对端地址位于其中的客户端无需 Bearer 令牌即可使用 /mcp。这会向这些网段中的所有设备授予完整的管理级 MCP 访问权限。请勿将服务暴露在可信 LAN 之外；此检查不会使用转发的客户端地址标头。

在浏览器中打开服务器的 LAN 地址。仪表板不会要求令牌，因此所有能够访问它的用户都可以查看元数据并管理 Telegram 身份。同源浏览器请求会自动获准；若前端使用单独的源，则必须将其添加到 TG_MCP_ALLOWED_ORIGINS。仅允许来自可信网络的 TCP 8765 和发现用 UDP 38475 流量。 当流量经过不可信网络时，请使用 VPN 或需要身份验证的反向代理。

Docker Compose 部署

将域名指向服务器并允许入站 TCP 80/443，然后运行：

cp .env.example .env
# Set TG_MCP_DOMAIN to the real hostname in .env.
docker compose build
docker compose run --rm --no-deps tg-mcp setup
docker compose up -d

打开 https://your-domain.example/ 进行初始设置。仪表板有意设置为无需令牌即可访问；请使用网络策略或需要身份验证的反向代理保护域名。 Agent 仍需使用 Bearer 令牌连接到 https://your-domain.example/mcp。

Compose 还会在端口 38475 上发布经过身份验证的 UDP 发现服务，并向同一专用网络上的客户端公布该 HTTPS 端点。必要时，请在两侧更改 TG_MCP_DISCOVERY_PORT，或者设置 TG_MCP_DISCOVERY=false，以关闭本地发现功能。

Caddy 会终止 HTTPS，不会将应用端口暴露到公网。应用容器以非特权用户运行，根文件系统为只读。每个状态卷只运行一个应用副本。

安全模型

• 状态目录必须设置为 0700 权限；敏感文件使用 0600 权限。
• 系统会拒绝符号链接、敏感文件的硬链接、归属外部用户的文件以及权限过于宽泛的文件。
• Web UI 不使用第三方脚本、字体、分析工具或远程资源。
• 能够访问服务器的客户端无需令牌即可访问仪表板账户数据和设置 API。除非操作员主动配置 TG_MCP_TRUSTED_NETWORKS，否则 MCP 端点需要 Bearer 令牌；启用此选项后，指定专用 CIDR 网段中的客户端将获得完整的 MCP 访问权限。
• Host 和 Origin 值会根据精确的允许列表进行检查；不接受通配符。
• 日志和操作历史不会记录消息正文、搜索词、凭据、二维码 URL 和 2FA 密码。
• 测试使用虚假的 Telegram 适配器，不会发送真实消息。

仅在服务停止时备份状态卷，并对备份进行加密存储。如果会话泄露，请在 Telegram → Devices 中撤销该会话。有关漏洞报告方式和操作详情及错误代码，请参阅 SECURITY.md 和俄语版 README。

本地聊天归档

可选择将聊天加入持久化本地历史记录、编辑版本观察和全文搜索。默认不保留已删除内容。请参阅归档设置和限制以及工具目录。

项目记忆与语义搜索支持基于来源的草稿、显式审批以及选择性启用的本地 Ollama 嵌入。各项目彼此隔离；来源的编辑和删除会使衍生记忆失效。无需嵌入模型即可进行关键词搜索。 可选后台 RAG会自动发现当前及未来的所有用户账户聊天、群组和频道，并维护本地嵌入。

已知限制

• 无法通过 Telegram 的云 API 使用秘密聊天。
• 不支持删除消息，也不支持分布式／多副本部署。
• 历史记录工具会按需读取 Telegram。只有明确选择的聊天才会复制到本地存档；观察到的覆盖范围和删除事件不保证完整。
• 当新消息在翻页期间到达时，基于位置的分页可能会重复或跳过项目。
• poll_updates 会在进程内存中保留最近的 2,000 个事件，并在重启后重置。

开发

uv sync --frozen
uv run ruff check .
uv run ruff format --check .
uv run pytest -q
node --test tests/ui-table-state.test.cjs
uv build
TG_MCP_DOMAIN=mcp.example.test docker compose config --quiet
docker build -t tg-account-mcp:local .

架构和贡献者设置说明见 docs/architecture.md 和 CONTRIBUTING.md。发布和注册步骤见 docs/PUBLISHING.md。

许可证

根据 Apache License 2.0 授权。

本地优先的消息检索

优先使用 find_messages(account_id, query, chat_id=..., telegram="auto") 作为消息检索工具。它会组合本地词法匹配和语义候选项，按账号／聊天／消息 ID 去重，并在本地结果或覆盖范围不足时，回退到一个有界的 Telegram 页面。telegram="never" 不会读取 Telegram；"always" 会验证新鲜度。可选的 date_from／date_to 为包含在内的 UTC 日期。include_context=true 只会读取排名最高的结果及其两侧各两条相邻消息，除非选择了仅本地模式。

检查 partial、warnings、local_coverage、semantic_partial 和来源信息。语义检索范围仍限制在指定范围内最近的 2,000 条已索引消息；词法搜索会覆盖保留的存档。无法保证账号级清单完整，因此自动账号级查询也可能会查询 Telegram。结果是有界排序，而非完整导出；分数不代表置信度。Telegram 游标必须通过返回的原生 cursor_tool（search_messages 或 search_all_messages）继续使用，并保留账号／查询／聊天／日期参数。

回退读取和上下文读取共用账号的自适应加载门控。Telegram 故障、冷却期或超时会保留本地结果，并附带明确警告。检索请求不会返回已删除内容，也不会自动启用、存档或重新索引任何来源。受聊天范围限制的令牌必须提供获准的 chat_id；在进行任何读取之前，系统会拒绝账号级检索。

持续文本与 S3 摄取

私聊始终启用文本 RAG 和所有受支持的附件类型。群组和频道的默认设置保持文本 RAG 启用、S3 禁用。在“设置” →“RAG 和 S3”下设置默认值，在 RAG 页面设置每个聊天的规则，或使用管理员命令 set_ingestion_policy。发现的聊天可以覆盖其类型的规则，也可以重新继承该规则。get_ingestion_policy 可读取单个聊天的有效规则。 全局更改需要不受身份或聊天限制的管理员令牌。已明确暂停的归档、已排除的聊天和已禁用的账号仍保持暂停状态。

RAG 文本和 S3 文件是独立的开关。S3 类型包括 photo、video、document、audio、voice、video_note、sticker、animation。说明文字可以进入文本 RAG；文件以原始二进制对象的形式存储，不进行 OCR 或转录。 禁用规则会停止后续摄取，并保留现有数据。重新启用文本 RAG 会恢复历史记录覆盖；启用 S3 会为现有已保存的附件元数据创建种子任务。新的实时消息会立即加入队列；传输是异步的，按从新到旧的顺序进行，并在已就绪账号之间公平轮转。Telegram 发现仍按配置的间隔运行。下载与历史记录读取共用持久化的自适应 Telegram 限流器；FloodWait 暂停和间隔延长同样适用于两者。语义嵌入仍在本地进行。

使用 TG_MCP_S3_ENDPOINT、TG_MCP_S3_REGION（默认为 garage）、TG_MCP_S3_BUCKET、TG_MCP_S3_PREFIX（默认为 telegram）、TG_MCP_S3_ACCESS_KEY 和 TG_MCP_S3_SECRET_KEY 配置私有 S3 兼容端点。 在私有环境文件中同时提供端点、存储桶和两项凭据；S3 需要后台 RAG 及其本地嵌入提供程序。端点必须位于环回或私有网络；不会使用公共端点和环境代理。请单独配置存储桶和受限凭据；切勿将其提交到代码库。

工作器会维护私有的可恢复暂存区、持久化上传意图和幂等对象键，在上传后检查对象长度和 SHA-256 元数据，并保留 5 GiB 本地可用空间。下载前已消失的 Telegram 文件会报告为已跳过。仪表板状态会报告排队中、已保存、失败和待删除的 S3 对象数量，不显示文件名或凭据。清除归档时会安排删除对象；media_cleanup_pending 会报告此异步清理队列。 Telegram 删除数据的保留策略遵循聊天现有的 retain_deleted 设置。请同时备份 SQLite 归档、暂存区、凭据和 S3 服务数据；同一台机器上的 S3 服务属于存储，而非独立备份。

仪表板表格和规则

RAG 页面将队列监控与可搜索的聊天注册表相结合。可按账户、聊天类型、状态、继承/自定义规则或 S3 策略筛选；可对结果排序，并选择每页显示 10/25/50/100 行。被排除的聊天仍会显示。点击聊天名称可直接编辑其规则；状态轮询期间，草稿和当前页选择会保留。 私人聊天规则为固定规则。默认群组/频道规则位于 Settings → RAG and S3；服务器/模型信息在 About the service 中以只读方式显示。

活动表支持筛选、排序和分页，范围为最近 30 天内保留的最近 100 项操作。页脚会注明此范围限制。历史记录覆盖率根据已知状态计算，而非估算 Telegram 总量的百分比。每个聊天的 S3 计数显示已上传对象的去重数量以及待处理/错误任务，不显示文件名或对象键。

队列栏显示嵌入速率、净传入文本速率、已保存文本积压量，以及根据队列净排空速率计算的预计剩余时间。图表跟踪已保存文本队列；其估算不包括尚未下载的 Telegram 历史记录。当队列增长或停止排空时，面板会显示相应状态，而不显示完成时间。展开的诊断信息包括账户速率控制和历史记录覆盖率。附件错误会单独报告，并显示重试状态；文本队列已处理完毕，并不意味着所有文件都已上传。Telegram 历史记录读取和附件下载各自保留共享的自适应间隔，不受本地嵌入吞吐量影响。

如果状态 API 不可用，面板会保留最后显示的数据，并标记为过期。规则保存失败时会保留草稿，以便重试；未保存的编辑会阻止筛选条件或页面更改，直到保存或取消。关闭规则不会删除已有数据。