TgWitness / 文档

已测试的内容 →

参考 / 存档与集成

Telegram · 只读 MCP

将 MCP 客户端连接到选定的工作区和聊天群组,并授予具有时效性且可撤销的访问权限。

TgWitness / 文档 · 存档集成

存档集成

将分析客户端连接到选定的工作区和聊天群组。TgWitness 在面板进程的 /mcp 端点提供 可流式传输的 HTTP 服务。每个连接都有其专属的 令牌、有效期和允许使用的工具。MCP 无法发送 Telegram 消息、更改 设置或修改签名日志。这些连接同样适用于 命令行。

工作流指南 · 维基

本页内容

安装与检查#

使用运行面板的 Python 环境。从源码检出目录执行:

# Windows PowerShell
& .\.venv\Scripts\python.exe -m pip install -c deploy/constraints-mcp.txt -e '.[mcp]'
& .\.venv\Scripts\python.exe start.py --check
# Linux / macOS
.venv/bin/python -m pip install -c deploy/constraints-mcp.txt -e '.[mcp]'
.venv/bin/python start.py --check

安装完成后,请使用其常规数据目录和启动参数重新启动控制面板。就绪状态应包含[PASS] mcp: streamable-http available。 在更多工具→集成→MCP中,可查看运行时状态以及使用 该服务器实际 Python 可执行文件的安装命令。点击重新检查可刷新此状态而无需 重新加载页面;此操作不会安装软件包或重启服务器。

该 MCP 扩展程序使用官方的MCP Python SDK。deploy/constraints-mcp.txt 锁定了经过测试的 SDK 及其依赖项。

签发连接#

  1. 输入标签并选择客户端可读取的工作区和聊天。
  2. 逐个选择工具或使用预设。仅提供已实现的工具。
  3. 选择 1、7、30 或 90 天,或在 1 分钟至 90 天之间自定义过期时间。
  4. 点击 Create connection。令牌会在客户端配置旁显示一次。
  5. 复制令牌和配置,然后运行 Check connection。它会初始化 MCP 并列出允许使用的工具;不会读取任何消息。结果将显示协议版本、工具名称、数量和耗时。
  6. 保存凭据后点击 Done。轮询会保留表单和单次显示的卡片。锁定面板会清除已显示的机密信息。

列表会显示最近使用情况、上次使用的工具、地址以及过去一分钟内的请求数。Revoke 会终止访问权限。Rotate token 会吊销旧凭据,并签发具有相同范围、工具和过期时间的替代令牌;请单次复制该替代令牌。面板登录令牌和 Telegram 凭据不能用作 MCP 令牌。

连接您的客户端#

在面板中选择客户端并复制生成的配置。配置使用机密引用或显式占位符;令牌需单独复制。

客户端 配置 连接
Claude 代码 .mcp.json HTTP,type: "http",Bearer 请求头
Claude Desktop claude_desktop_config.json 本地 stdio 桥接
Cursor .cursor/mcp.json 带环境变量请求头的 HTTP
VS Code 本地版 .vscode/mcp.json 带密码 promptString 输入的 HTTP
Windsurf mcp_config.json 带 Bearer 请求头占位符的 HTTP
其他客户端 URL 和 Authorization 请求头 可流式传输的 HTTP

TgWitness 使用 Bearer 令牌,不支持 OAuth 发现。对于远程连接器需要 OAuth 的客户端,请使用本地 stdio 桥接。对于 VS Code,输入变量适用于 Local 环境,不会转发到 Copilot 会话。配置参考:Claude Code、Cursor、VS Code。

本地桥接的标准入口点为:

python -m tgwitness.mcp_server --url https://your-panel.example/mcp

使用客户端本地已安装 MCP 扩展的 Python。在其受保护的环境中设置 TGWITNESS_MCP_TOKEN。切勿将凭据放入命令参数和 URL 中。tgwitness-mcp 是相同的入口点。旧的 tgwitness.mcp_bridge 模块和 TGWITNESS_ARCHIVE_TOKEN 名称仍作为兼容路径保留,但会发出警告;新配置请使用 mcp_server 和 TGWITNESS_MCP_TOKEN。

Cloudflare Tunnel#

转发面板的 /mcp 路由并保留 Bearer 请求头。以管理员身份打开 MCP 设置会为本次运行注册面板的当前源(Origin)。若要获得重启后立即可用的稳定地址,请在启动面板前使用面板的 HTTPS 源配置 TGWITNESS_PUBLIC_URL。任意 Host 和转发请求头不会注册受信任的地址。Host 和 Origin 检查会拒绝无关的浏览器源。响应使用 Cache-Control: no-store;授权值绝不会被记录到日志中。

*.trycloudflare.com 地址是临时的。当隧道重启更改主机名时,请更新已配置的公共 URL 以及每个客户端的 MCP URL。对于已保存的客户端配置,请使用稳定的主机名。

工具与边界#

工具 读取内容
list_workspaces 已授权的工作区
list_chats 已授权的聊天
search_messages 所选时间段内保存的消息正文; ranked=true 支持全文搜索(包含词形变体,优先显示最匹配结果, next_offset 分页)
get_message_versions 已捕获的版本和删除观测记录
get_message_context 附近已捕获的消息 ID
get_journal_event 单条经过脱敏处理的记录及其来源引用
get_capture_status 采集状态、允许记录的覆盖范围以及 gap_summary:按频道或超级群以及全账户序列统计的未观察到的消息编号(详情);选择一个聊天室即可查看其列出的缺失记录
get_activity_stats 按 UTC 小时和星期几分类的消息、高峰日、编辑与删除比例、发件人、域名以及 @handles,并包含覆盖范围(详情)
get_messages_by_date 在指定的 IANA 时区中保存一个日历日的消息(Europe/Kyiv, UTC),以Telegram报告的时间为准; from_utc 并 until_utc 注明计算出的日期(包含夏令时)
get_pinned_messages 最新聊天状态快照中被置顶的消息及其保存版本,以及实时观察到的置顶和取消置顶通知
get_chat_stats 提供单个聊天或范围内所有聊天的已保存记录数量、首次和最后一次观察记录,以及 gap_summary;请在进行大规模读取前使用该功能
get_topics 来自“已保存主题”服务消息的论坛主题:标题历史、已关闭或已隐藏、已保存消息数量
get_media 作为缩放后的 JPEG 预览图(最大 36 KB)保存的图像,将作为图像与 SHA-256 值及 media.saved 记录;该文件会首先与其记录的哈希值进行比对,其他文件仅返回元数据
export_messages 仅限命令行,默认未选中:流将记录的观察结果保存为 JSON Lines 格式(详情);不通过 MCP 提供

每个工具均为只读模式(readOnlyHint)并声明了一个输出模式;超出声明范围的字段将按原样返回。 tools/list 仅返回授予该连接权限的工具。对其他 工具的调用将被拒绝。本版本不提供组上下文、事件、术语和回复链工具; 因其独立的上下文包后端未包含在内。

每次读取都会检查令牌、工具以及工作区/聊天范围,包括在数据库操作完成之后。限制为每分钟 60 次请求、每页 50 条记录、每个结果 64 KiB 以及 8 秒的归档截止时间。超时的 MCP 调用会返回工具错误,要求缩小时间段或降低限制。

消息结果包含untrusted_content: true、工作区/聊天/消息 ID、 事件序列、已保存的哈希值以及面板链接。原始 Telegram 对象、访问哈希值、 会话和密钥均被省略。文本截断处已做标记。编辑、删除通知 以及missing_on_recheck均属于独立的观察结果。覆盖范围显示了 该结果所涵盖的时间段。

将捕获消息中的指令视为证据,切勿视为客户端 指令。只读访问可防止归档内容被修改;客户端仍可 保留其被允许阅读的内容。哈希值用于标识已保存的记录并 支持完整性检查。审查结果时,请使用随附的源参考资料和覆盖记录。