TgWitness / 文档
简体中文
EnglishРусскийУкраїнськаEspañolPortuguês (Brasil)Türkçeالعربيةفارسیاردوहिन्दीBahasa IndonesiaTiếng Việt简体中文FrançaisDeutschItalianoO‘zbekcha한국어繁體中文Bahasa MelayuPolski日本語ไทยעבריתবাংলা

参考 / 存档与集成

只读 MCP

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

将分析员客户端连接到选定的工作区和聊天。TgWitness 在面板进程的 /mcp 处提供 Streamable 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。Integrations → MCP 会显示运行时状态以及使用该服务器实际 Python 可执行文件的安装命令。Re-check 可在不重新加载页面的情况下刷新此状态；它不会安装软件包或重启服务器。

MCP 扩展使用官方的 MCP Python SDK。deploy/constraints-mcp.txt 锁定了经过测试的 SDK 及其依赖项。这些功能需要当前的源码；0.7.0 便携预览版早于这些功能发布。

签发连接#

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

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

连接您的客户端#

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

客户端 配置 连接
Claude Code .mcp.json HTTP，type: "http"，Bearer 请求头
Claude Desktop claude_desktop_config.json 本地 stdio 桥接
Cursor .cursor/mcp.json 带环境变量请求头的 HTTP
VS Code Local .vscode/mcp.json 带密码 promptString 输入的 HTTP
Windsurf mcp_config.json 带 Bearer 请求头占位符的 HTTP
其他客户端 URL 和 Authorization 请求头 Streamable 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 选定时间段内已保存的消息文本
get_message_versions 已捕获的版本和删除观测记录
get_message_context 附近已捕获的消息 ID
get_journal_event 单条经过脱敏处理的记录及其来源引用
get_capture_status 采集状态和允许的覆盖范围记录

tools/list 仅返回授予该连接的工具。对其他工具的调用将被拒绝。此版本不提供群组上下文、事件片段（episode）、术语和回复链工具；未包含它们独立的上下文包后端。

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

消息结果包含 untrusted_content: true、工作区/聊天/消息 ID、事件序列、已保存的哈希值以及面板链接。原始 Telegram 对象、访问哈希、会话和密钥均被省略。文本截断会予以标记。编辑、删除通知和 missing_on_recheck 是不同的观测记录。缺失记录并不能证明某个事件从未发生。

请将已捕获消息中的指令视为证据，切勿将其作为客户端指令。只读访问权限可防止归档被更改；但客户端仍可保留允许其读取的内容。哈希值用于标识已保存的记录并支持完整性检查；它们不能证明 Telegram 作者身份或捕获的完整性。