# Telegram · 只读 MCP

Canonical page: https://phishdestroy.io/tgwitness/zh/docs/reference/mcp/

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

[Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.io/tgwitness/zh/llms.txt)

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

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [存档集成](https://phishdestroy.io/tgwitness/zh/docs/reference/cli/)

![存档集成](https://phishdestroy.io/tgwitness/assets/chapter-integrations.svg?v=367d9d210074)

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

[工作流指南](https://phishdestroy.io/tgwitness/docs/archive/) · [维基](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md)

**本页内容**

- [安装与检查](https://phishdestroy.io/tgwitness/zh/docs/reference/mcp/#install-and-check)
- [建立连接](https://phishdestroy.io/tgwitness/zh/docs/reference/mcp/#issue-a-connection)
- [连接您的客户端](https://phishdestroy.io/tgwitness/zh/docs/reference/mcp/#connect-your-client)
- [Cloudflare Tunnel](https://phishdestroy.io/tgwitness/zh/docs/reference/mcp/#cloudflare-tunnel)
- [工具与边界](https://phishdestroy.io/tgwitness/zh/docs/reference/mcp/#tools-and-boundaries)

## 安装与检查

使用运行面板的 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](https://github.com/modelcontextprotocol/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](https://code.claude.com/docs/en/mcp)、[Cursor](https://prod.cursor.com/docs/mcp)、[VS Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)。

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

```
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` 支持[全文搜索](https://phishdestroy.io/tgwitness/zh/docs/reference/search/)（包含词形变体，优先显示最匹配结果， `next_offset` 分页） |
| `get_message_versions` | 已捕获的版本和删除观测记录 |
| `get_message_context` | 附近已捕获的消息 ID |
| `get_journal_event` | 单条经过脱敏处理的记录及其来源引用 |
| `get_capture_status` | 采集状态、允许记录的覆盖范围以及 `gap_summary`：按频道或超级群以及全账户序列统计的未观察到的消息编号（[详情](https://phishdestroy.io/tgwitness/zh/docs/reference/evidence/#missing-message-numbers-gap_summary)）；选择一个聊天室即可查看其列出的缺失记录 |
| `get_activity_stats` | 按 UTC 小时和星期几分类的消息、高峰日、编辑与删除比例、发件人、域名以及 `@handles`，并包含覆盖范围（[详情](https://phishdestroy.io/tgwitness/zh/docs/reference/cli/#activity-statistics)） |
| `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 格式（[详情](https://phishdestroy.io/tgwitness/zh/docs/reference/cli/#export)）；不通过 MCP 提供 |

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

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

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

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