Telegram MCP Server

Telegram MCP 服务

面向真实账号的 Telegram MCP——默认安全、由 TDLib 驱动，可用于生产环境。

一个本地优先的 Model Context Protocol 服务，让 AI Agent 能访问真实的 Telegram 账号，而无需将账号密钥交给它。服务默认以只读模式启动，在你选择启用之前会隐藏写入工具，并通过 STDIO 为桌面 客户端提供服务，或通过 /mcp 上的 Streamable HTTP 为托管部署提供服务。

为什么选择它？

• 默认安全——以只读模式启动，并采用精简的 inbox/reader 配置； 在你启用之前，写入工具和消耗配额的工具会对模型隐藏，而不只是被阻止。
• 不依赖客户端的人为审批——破坏性工具会先征求人工同意： 如果 MCP 主机支持 elicitation，就通过主机进行；否则由此服务托管一个一次性回环页面。 无论哪种方式，问题都会在模型本轮之外发出，答案也会在模型本轮之外返回，因此，注入的指令只能让模型请求封禁，不能让它批准封禁。
• Agent 可重试的发送操作——idempotency_key 会将丢失的响应转为已存储的回执，而不是重复发送消息；未经确认的发送操作会报告为 UNKNOWN， 绝不会被静默重发。
• 真实用户账号，而不只是机器人——基于 TDLib（通过 tdlight-java）构建，因此 Agent 能读取并操作你的真实账号，而不局限于 Bot API 的功能子集。
• 多账号隔离——每个账号都有独立会话、强制选择机制和受限 API 密钥；读取操作不会跨账号进行。
• 两种传输方式——STDIO 适用于 Claude Desktop / Cursor / VS Code / Codex，Streamable HTTP 适用于托管服务。
• 无需安装 JDK——为 Windows、Linux x64/ARM64 和 Apple 芯片 macOS 提供内含运行时的发行包，并附带校验和、SBOM 和已签名的容器摘要。

该图片仅为示意图；真实录屏即将推出。

安全地首次运行

内含运行时的发行包无需 JDK、Gradle、Git、Python 或 Node.js。如果可以，首次运行时请使用测试账号。

1. 安装（Apple 芯片 macOS / 使用 Homebrew 的 Linux）：

brew install --formula https://github.com/tolboy/telegram-mcp-tdlib/releases/latest/download/telegram-mcp.rb

使用 Scoop 的 Windows：

scoop install https://github.com/tolboy/telegram-mcp-tdlib/releases/latest/download/telegram-mcp.json

2. 登录并扫描二维码——一次性验证码不会进入 shell 历史记录：

telegram-mcp auth --method qr

3. 检查会话是否就绪——这会读取本地状态，不会启动服务：

telegram-mcp session doctor

不要自行运行 serve --transport stdio 来试用。使用 STDIO 时，你的 AI 客户端会启动服务并管理其生命周期；在终端中启动的副本会占用 TDLib 会话，而客户端自己的副本随后会因无法锁定 td.binlog 而以代码 2 退出。请将命令交给客户端（如下所示），让它负责启动。

然后先尝试一个不会造成任何更改的提示词：

“总结我最近的 20 段对话。不要发送或修改任何内容。”

在此模式下，写入工具和消耗配额的工具会完全从工具列表中移除，因此模型没有可调用的破坏性工具。只有在检查过可用工具后，才切换到 MCP_READ_ONLY=false。启用后，请同时设置 MCP_DESTRUCTIVE_APPROVAL=auto，这样删除、封禁和退出操作都会等待你的答复：有可用的主机 elicitation 时通过主机征求同意，否则通过服务的回环页面征求同意，而不会信任模型自己的 "confirmed": true。

连接客户端

生成配置项，而不是手动抄写——它会填入客户端实际需要的密钥，并固定生成时使用的版本：

telegram-mcp config --client claude

--client claude-code|cursor|vscode|codex 用于切换目标——Codex 使用 TOML，VS Code 使用其实际读取的 servers 键，Claude Code 则需要显式指定传输 type。--writes 会启用写入工具以及用于保护破坏性操作的审批提示词——请将它与支持写入的 --profile inbox|community-admin|all 搭配使用，因为默认的 reader 工具集会在检查只读模式之前隐藏写入工具。--docker default 会生成带固定镜像版本的容器配置项，而 --http default 会生成供 Claude Code、Cursor、VS Code 或 Codex 使用的共享守护进程配置项。Claude Desktop 不会从 claude_desktop_config.json 读取远程服务；请改为在“设置” → “连接器”中添加可通过网络访问的远程端点。Claude 远程连接器不接受生成器自定义的 API 密钥标头，因此此服务必须通过 HTTPS 暴露，并设置 MCP_AUTH_MODE=oauth。因此，生成器会拒绝 --client claude --http。

对于桌面客户端，STDIO 是最简单的方式。生成的配置项如下：

{
  "mcpServers": {
    "telegram": {
      "command": "telegram-mcp",
      "args": ["serve", "--transport", "stdio"],
      "env": {
        "TDLIB_API_ID": "123456",
        "TDLIB_API_HASH_FILE": "/absolute/path/to/telegram-api-hash",
        "MCP_TOOL_PROFILE": "inbox",
        "MCP_READ_ONLY": "true"
      }
    }
  }
}

• Claude Desktop — 将上面的代码块添加到 claude_desktop_config.json，然后从系统托盘退出应用并重新启动。使用“设置” → “开发者” → “编辑配置”打开文件：这会根据你的构建版本打开正确的文件。手动编辑 %APPDATA%\Claude 仅适用于安装程序版本——Microsoft Store 版本以 MSIX 打包，其配置文件位于 %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\。
• Cursor — 将其添加到 ~/.cursor/mcp.json（或选择“设置” → “MCP” → “添加”）。
• VS Code — 使用 .vscode/mcp.json；VS Code 将顶层键命名为 servers，而不是 mcpServers，并且要求显式指定 "type": "stdio" 或 "type": "http"。

如需让多个客户端共享一个本地进程，请使用 telegram-mcp daemon start 和 telegram-mcp daemon attach --client cursor（或 codex、vscode、claude-code）。有关状态、停止和入门说明，请参阅托管本地守护进程。

如需使用托管 HTTP 部署，而不是 STDIO：

docker run --rm -p 127.0.0.1:8080:8080 \
  -e TDLIB_API_ID -e TDLIB_API_HASH -e MCP_API_KEY \
  ghcr.io/tolboy/telegram-mcp-tdlib:latest

有关各平台和客户端的具体变体，请参阅 CLI 和 STDIO、交互式身份验证和客户端兼容性。

使用示例

如需可重复使用的 Agent 指令，请安装免费的 Telegram 收件箱助手技能。 需要 server 1.17.2 或更高版本。使用共享守护进程的 Claude Desktop 用户可以使用可选的工具桥接，该功能随运行时软件包一起提供，并附有 Python 依赖项说明。 其设置指南包含客户端配置模板，并说明了另行配置本地服务和 Telegram 授权的要求。该技能会以只读模式总结和搜索。

可直接复制粘贴的真实任务配置和提示词，每项都使用完成任务所需的最小工具集： 总结收件箱、 查找丢失的消息、 调研公开群组、 只读社区健康检查、 以及起草回复但不发送——索引见 docs/recipes。

对比

大多数 Telegram MCP 服务会封装 Bot API 或 Telethon 用户会话，并一次性向模型开放所有功能。本项目专为让 Agent 安全连接到你在意的真实账号而优化：

维度	本服务	常见的 Telethon / Bot-API MCP 服务
账号访问	通过 TDLib（tdlight-java）访问真实用户账号	通常仅支持机器人，或单个 Telethon 用户会话
默认状态	只读；启用前会隐藏写入／配额工具	通常一开始就开放所有工具
多账号	会话隔离、必须选择账号、密钥按账号限定、不会跨账号扇出读取	单个账号，或隐式扇出
传输方式	STDIO 和 Streamable HTTP /mcp	通常仅支持 STDIO
安全措施	操作确认、审计日志、防垃圾信息限制、聊天白名单、将不可信内容标记出来	很少
分发方式	已签名的运行时包（无需 JDK）、SBOM + 来源证明、GHCR 镜像	通过 pip/npx 从源代码安装

更完整的架构对比（TDLib、Telethon 与 Bot API，以及“隐藏而非阻止”的重要性）请参阅 docs/COMPARISON.md。与主流公开服务的详细对比基准（附日期）——包括我们有意不提供的功能（原始 MTProto 逃生通道、所有权转移、批量导出联系人）——请参阅 PUBLIC_BENCHMARK_AND_ROADMAP.md。

工具配置

你不必在第一天就开放 116 个工具。MCP_TOOL_PROFILE 会在客户端看到工具之前缩小其可见范围，且不会削弱账号范围限定、只读模式、操作确认、审计或防垃圾信息措施：

配置	可用范围
reader	始终不会修改数据，适合初次体验
inbox	个人消息、草稿、媒体、联系人、隐私
community-admin	管理、群组／频道、权限、机器人命令
research	有范围限制的账号／公开内容发现与读取
all	全部工具（需主动选择启用）

各配置范围的具体用途请参阅 TOOL_PROFILES.md。

功能

• 116 个 MCP 工具 — 消息、投票、已读回执、定时发送、聊天、文件夹、邀请链接管理、联系人、媒体、草稿、隐私、机器人命令、详细的群组权限、个人资料、搜索和账号路由。
• 通过 tdlight-java 使用 TDLib — 使用真实用户账号，而不只是 Bot API。
• 隔离的多账号模式 — 独立会话、强制选择账号，以及可选的按密钥划分账号范围，不会跨账号读取。
• 默认安全 — 只读工具界面；执行破坏性操作需经人工批准（MCP_DESTRUCTIVE_APPROVAL，通过宿主或本地回环页面）；并提供面向任务的配置（reader/inbox/community-admin/research/all）。
• 可恢复的发送 — 文本、回复、文件、语音、贴纸、转发和定时消息均支持可选的幂等键和持久化回执；请参阅发送恢复。
• 按客户端设置权限 — 经审核的 JSON 文件会为每个客户端授予对指定账号和聊天执行 read、download、mutate、quota 或 policy 操作的权限；其他操作一律拒绝。请参阅权限。
• 提供可信答案 — 每个工具都会发布类型化输出架构；错误会附带稳定的代码和重试指引；导出和搜索会说明结果是否完整。
• 长时间运行的任务 — 精简的收件箱和对话工具设有响应预算；导出可在重启后继续；变更日志会报告自身的数据缺失情况。
• 两种传输方式 — 面向桌面客户端的 STDIO，以及 Streamable HTTP /mcp（Spring AI 2.0 / MCP SDK 2.0），并支持 API 密钥身份验证；telegram-mcp daemon 可让多个客户端共用一个本地服务。
• 防护措施 — 审计日志、通过 Resilience4j 限流器（30 req/s）和熔断器实现的反垃圾机制、聊天允许列表、提示词注入模式，以及不可信内容标记。
• 可观测性 — Micrometer 指标、Prometheus 端点，以及带有 MDC（traceId、sessionId、toolName）的结构化 JSON 日志。
• 经过验证且包含运行时的发行版 — 提供 Windows x64、Linux x64/ARM64 和 Apple 芯片 macOS 软件包，附带校验和、SBOM 及签名容器摘要 — 无需 JDK。

更多功能

• 实体解析 — 自动解析 @username、+phone 或数字 ID。
• MCP 行为注解 — 每个公开的工具都会声明只读、破坏性、重试和开放世界提示，帮助客户端提供更安全的用户体验。
• 结构化且带标记的输出 — 提供向后兼容的 JSON 文本和 structuredContent；明确标记由 Telegram 控制的字段为不可信内容，并转义用于控制显示的 Unicode 字符。
• 便于宿主发现 — 通过 /.well-known/mcp-server.json 为安装程序、桌面宿主和服务管理器提供发现支持。
• 文件安全服务，用于安全上传媒体；Actuator 健康状态/信息/指标；支持配置超时的优雅关闭。
• 多阶段 Docker 构建 + docker-compose，并支持开发环境热重载。
• 包含运行时的应用映像 — 受支持的发行版压缩包自带 Java 运行时，并会在发布前通过实际的 STDIO 握手测试。
• 离线会话诊断工具 — 检查已配置的 TDLib 状态路径和锁的可用性，无需启动 TDLib 或输出机密信息。
• 整洁架构 — config / model / client / service / tool / security / util / exception。
• 不受语言限制的公开搜索 — 调用方可使用任意语言传入同义词、译文和拼写变体；产品特定的策略解释由 MCP 宿主负责。

## 技术栈

组件	版本
Java	25
Kotlin	2.4.21
Spring Boot	4.1.1
Spring AI MCP	2.0.1
MCP Java SDK	2.1.0
TDLib (tdlight)	3.5.9+td.1.8.68
Gradle	9.8.2
Resilience4j	2.4.0

快速开始

前提条件

• Java 25+（或使用 Docker）
• 从 https://my.telegram.org 获取 Telegram API 凭据（TDLIB_API_ID、TDLIB_API_HASH）
• 必须且只能选择一种身份验证模式：用户账号模式使用 TDLIB_PHONE_NUMBER，机器人模式使用 TDLIB_BOT_TOKEN

1. 克隆并配置

git clone https://github.com/tolboy/telegram-mcp-tdlib.git
cd telegram-mcp-tdlib
cp .env.example .env
# Edit .env — set TDLIB_API_ID, TDLIB_API_HASH, one of TDLIB_PHONE_NUMBER/TDLIB_BOT_TOKEN, and MCP_API_KEY

在 Windows PowerShell 中，请使用 Copy-Item .env.example .env，而不是 cp。

2. 在本地运行

./gradlew bootRun

服务将在 http://localhost:8080 启动。其 MCP Streamable HTTP 端点为 http://localhost:8080/mcp。

开始后的 60 秒

1. 在客户端中添加远程 Streamable HTTP MCP 服务，URL 为 http://127.0.0.1:8080/mcp，并设置 Authorization: Bearer <MCP_API_KEY>。 Cursor、VS Code、Codex、Claude Code 和 Inspector 均可使用此本地 HTTP 端点。Claude Desktop 的配置文件支持上方的本地 STDIO 条目； 其远程连接器需通过“设置”→“连接器”添加，并且需要可通过网络访问的 HTTPS 端点以及 MCP_AUTH_MODE=oauth，而不是此环回 URL 加自定义标头。 具体连接信息见 MCP_CLIENT_COMPATIBILITY.md。

2. 安全起步：设置 MCP_READ_ONLY=true，并选择一个专注的功能范围，例如 MCP_TOOL_PROFILE=inbox 或 MCP_TOOL_PROFILE=research。

3. 向客户端提出以下任一具体的首个问题：

   • 收件箱：“总结最近 20 个相关对话。不要发送或修改任何内容。”
   • 社区：“显示此群组中近期的管理员操作和默认权限；提出更改建议，但不要应用。”
   • 研究：“查找匹配这些英语和俄语查询变体的公开聊天，并根据描述和近期消息提供证据。”

仅在检查已发现的功能范围后，才将 MCP_READ_ONLY=false； 破坏性操作默认仍需确认。

在 Windows 上，Gradle 默认将输出写入系统临时目录，以避免同步文件夹中的文件锁问题。设置 KTM_BUILD_DIR 或传入 -Pktm.buildDir=... 可覆盖此设置。

3. 使用 Docker 运行

docker compose up --build

compose 栈会将 TDLib 会话数据保存在 tdlib-data 卷中，将下载内容保存在 telegram-downloads 中，并将 ${MCP_UPLOADS_DIR:-./docker-data/uploads} 挂载到容器中的 /data/uploads，供上传/下载工具使用。

默认情况下，compose 通过 MCP_BIND_HOST 将服务绑定到 127.0.0.1，避免意外将本地沙盒/开发环境暴露到局域网。

启用热重载的开发模式：

docker compose --profile dev up telegram-mcp-dev

启用 Prometheus 监控：

docker compose --profile monitoring up

生产环境说明：请在容器前配置 TLS 终止（反向代理、入口或负载均衡器）。除可信的本地开发网络外，不应通过明文 HTTP 传输 API 密钥。

本地沙盒安装与远程/VPS 暴露的部署指南见 docs/DEPLOYMENT_MODES.md。

多服务 MCP 主机或安装程序的连接器发现说明见 docs/CONNECTOR_DISCOVERY.md。

客户端兼容性、可移植的 JSON-Schema 配置文件以及 Streamable HTTP 冒烟测试见 MCP_CLIENT_COMPATIBILITY.md。

TDLib 会话的离线安全检查与清理说明见 SESSION_MAINTENANCE.md。

与领先的公开 Telegram MCP 服务的比较以及后续工作的优先级见 PUBLIC_BENCHMARK_AND_ROADMAP.md。

发布版本

CI 会在每个拉取请求和推送到 master 时运行。经过签署确认的发布版本是一个采用 vX.Y.Z 格式的 Git 标签；发布工作流会构建镜像、针对已推送的摘要运行跨平台工具表面冒烟测试和容器生命周期契约测试、为其生成证明并签名，然后才将公开标签（latest、X.Y.Z、X.Y、不可变的 sha-<commit> 以及 -stdio 变体）指向该确切摘要——之后还会验证每个标签都解析到该摘要。Windows x64、Linux x64/ARM64 和 macOS ARM64 的发布包也会一并提供。公开发布版本包含可运行 JAR 的 SPDX SBOM、发布资源的 GitHub 来源证明，以及针对容器摘要的无密钥 Sigstore 签名和来源证明。请参阅发布包验证。

请使用明确的 semver 标签进行可复现部署。v1.0.0 是 Streamable HTTP / MCP SDK 2.0 的首个公开基线版本；v1.1.0 增加了账户隔离、范围限定密钥和跨平台原生打包；v1.2.0 增加了高级语音笔记转写和中性包命名空间；v1.3.0 增加了隐私、机器人命令、详细的群组权限控制和经过验证的发布包；v1.4.0 增加了专用 MCP 工具配置；v1.7.x 增加了 STDIO 传输、带交互式身份验证向导的 CLI、结构化工具输出、可选的 OAuth 资源服务器模式，以及包含运行时的发布镜像；v1.13.0 增加了通过宿主或环回页面对破坏性工具进行人工审批，以及用于生成客户端条目的 telegram-mcp config；v1.14.0 将每个已发布镜像标签都关联到通过验证和签名的摘要；v1.15.0 使运行中的构建版本可通过连接器自身的响应进行核验；v1.16.0 修复了交互式登录：授权请求现在会实际到达 TDLib，第二次登录尝试不再中止进程，身份验证状态会说明 Telegram 将验证码发送到了哪里；v1.17.0 增加了可恢复的带键发送、按客户端划分的权限、所有工具的类型化输出和结构化错误、精简任务工具、带更改日志的可恢复导出，以及托管的本地守护进程。完整历史记录请参阅 CHANGELOG.md。

若要确定实际响应的发布版本，请调用 _manifest 工具：响应会在 schemaVersion 旁提供 serverVersion。该版本从 JAR 自身的构建元数据读取——即根据发布标签派生的 Gradle 版本——因此无法通过 MCP_SERVER_VERSION 改写；同一制品上的 telegram-mcp version 也会输出相同字符串。

当前 TDLight 原生版本发布了 Apple 芯片版 macOS 二进制文件，但未提供 Intel macOS 分类器。服务器在 JVM/路径层面支持 Intel macOS，但要在该平台上运行基于 TDLib 的 Telegram 访问功能，需要上游提供原生包。

为当前匹配的平台创建包含运行时的应用镜像：

./scripts/package-app-image.ps1 -Version <version> -Target windows-x64 -OutputDirectory release-assets

构建会验证实际的 BOOT-INF/lib 内容、启动器报告的版本以及实时 STDIO 握手。有关目标矩阵，请参阅 RELEASE_BUNDLES.md。

git checkout master
git pull --rebase origin master
git tag -a vX.Y.Z -m "Telegram MCP Server vX.Y.Z"
git push origin master vX.Y.Z

环境变量

TDLib（主要 Telegram 客户端）

变量	必填	默认值	说明
TDLIB_API_ID	是*	—	来自 https://my.telegram.org 的 API ID
TDLIB_API_HASH	是*	—	来自 https://my.telegram.org 的 API 哈希值
TDLIB_API_HASH_FILE	否	—	TDLIB_API_HASH 的密钥文件替代项
TDLIB_PHONE_NUMBER	否†	—	用户账号模式下的电话号码（可完整访问 API）
TDLIB_BOT_TOKEN	否†	—	机器人模式下的 Bot 令牌
TDLIB_BOT_TOKEN_FILE	否	—	Bot 令牌的密钥文件替代项
TDLIB_2FA_PASSWORD	否	—	两步验证密码（无头启动时提供）
TDLIB_2FA_PASSWORD_FILE	否	—	两步验证密码的密钥文件替代项
TDLIB_AUTH_CODE	否	—	一次性登录验证码（首次无头运行时提供）
TDLIB_AUTH_CODE_FILE	否	—	登录验证码的密钥文件替代项
TDLIB_DATA_DIR	否	操作系统应用数据目录	会话数据库目录
TDLIB_DOWNLOADS_DIR	否	（数据目录下）	下载媒体文件的目录
TDLIB_LOG_VERBOSITY	否	1	TDLib 原生日志详细程度（0–10）
TDLIB_SYSTEM_LANGUAGE_CODE	否	en	Telegram 会话报告的语言代码
TDLIB_DEVICE_MODEL	否	Telegram MCP Server	Telegram 会话设置中显示的易识别设备标签
TDLIB_PROXY_TYPE	否	—	socks5、http（HTTP CONNECT）或 mtproto
TDLIB_PROXY_SERVER / TDLIB_PROXY_PORT	使用代理时必填	—	代理主机名/IP 和端口
TDLIB_PROXY_USERNAME	否	—	SOCKS5/HTTP 代理用户名（也需要提供密码）
TDLIB_PROXY_PASSWORD / _FILE	否	—	SOCKS5/HTTP 代理密码；_FILE 是挂载密钥的替代方式
TDLIB_PROXY_SECRET / _FILE	仅限 MTProto	—	MTProto 密钥；_FILE 是挂载密钥的替代方式
TDLIB_PROXY_HTTP_ONLY	否	false	将 HTTP 代理限制为仅处理 HTTP 请求；通常在使用 CONNECT 时保持 false

* 启用 TDLib 集成时必填。
† 必须且只能设置一个：TDLIB_PHONE_NUMBER 或 TDLIB_BOT_TOKEN。

非交互式身份验证：在全新容器中，设置一次 TDLIB_AUTH_CODE（如果启用了两步验证，还需设置 TDLIB_2FA_PASSWORD）。会话持久化到 TDLIB_DATA_DIR 后，重启时无需再设置这两项。每个直接设置的密钥都有互斥的 *_FILE 替代项，可用于 Docker/Podman/Kubernetes 密钥挂载。

首次在本地登录时，如不想将一次性验证码放入环境变量，请使用 INTERACTIVE_AUTH.md 中记录的手机号/验证码或 QR 流程。TDLIB_DEVICE_MODEL 和 TDLIB_SYSTEM_LANGUAGE_CODE 用于控制 Telegram 设置 → 设备 中显示的易识别会话身份。

静态数据加密说明：SimpleTelegramClient（tdlight-java）不提供 TDLib 数据库加密密钥。对于生产环境，应在文件系统层面加密 TDLIB_DATA_DIR 卷（LUKS、FileVault、EFS），而不要依赖库级别的标志。TdLibProperties.kt 中还提供了 use-file-database、use-chat-info-database、use-message-database 开关。

Telegram 代理

服务器会在登录前配置 TDLib 自带的代理，因此初始身份验证和正常的 Telegram 流量都会通过该代理。请使用以下任一完整配置；代理设置不完整或无效时，启动会失败，账号无法连接。

# SOCKS5 with optional username/password authentication
TDLIB_PROXY_TYPE=socks5
TDLIB_PROXY_SERVER=proxy.example.net
TDLIB_PROXY_PORT=1080
TDLIB_PROXY_USERNAME=connector
TDLIB_PROXY_PASSWORD_FILE=/run/secrets/telegram_proxy_password

# HTTP CONNECT (set HTTP_ONLY=false to route all TDLib traffic through it)
# TDLIB_PROXY_TYPE=http
# TDLIB_PROXY_SERVER=proxy.example.net
# TDLIB_PROXY_PORT=3128
# TDLIB_PROXY_HTTP_ONLY=false

# MTProto (secret must be supplied directly or through *_FILE)
# TDLIB_PROXY_TYPE=mtproto
# TDLIB_PROXY_SERVER=proxy.example.net
# TDLIB_PROXY_PORT=443
# TDLIB_PROXY_SECRET_FILE=/run/secrets/telegram_mtproto_secret

命名账号可以使用 TELEGRAM_ACCOUNTS_<LABEL>_PROXY_* 配置独立设置，例如 TELEGRAM_ACCOUNTS_WORK_PROXY_TYPE=socks5。账号代理不会回退到其他账号的凭据或 TDLib 会话。在 Docker 中使用 *_FILE 时，请将密钥文件挂载到容器中，并设置容器内的路径。

服务与安全

变量	必填	默认值	描述
TELEGRAM_BOT_TOKEN	否	—	旧版 Bot API 令牌（仅作回退）
TELEGRAM_BOT_USERNAME	否	—	Bot 用户名（用于日志记录）
TELEGRAM_ALLOWED_CHAT_IDS	否	（全部允许）	以逗号分隔的允许访问的聊天 ID
MCP_API_KEY	远程 API 密钥模式*	—	用于 MCP 端点身份验证的 API 密钥
MCP_API_KEY_FILE	否	—	MCP_API_KEY 的密钥文件替代项
MCP_AUTH_HEADER	否	Authorization	API 密钥的标头名称
MCP_READ_ONLY	否	true	禁止写入/修改类工具；本地下载可通过下方单独选择启用
MCP_READ_ONLY_ALLOW_DOWNLOADS	否	false	允许在只读模式及 reader/research 配置中使用本地 download_media，并保留聊天/账户访问检查
MCP_PERMISSIONS_FILE	否	空	经审核的 JSON 授权，用于控制客户端/账户/操作/聊天访问；参见权限和本地编辑器
MCP_TOOL_PROFILE	否	reader	all、reader、inbox、community-admin 或 research
MCP_TOOL_ALLOW	否	（配置中的工具）	经过配置筛选后保留的精确名称，以逗号分隔
MCP_TOOL_DENY	否	—	经过允许列表筛选后隐藏的精确名称，以逗号分隔
MCP_TRANSPORT	否	streamable-http	streamable-http 或 stdio；CLI --transport 优先
MCP_CONFIRMATION_REQUIRED	否	true	对破坏性工具要求调用方确认（"confirmed": true）；这不能证明获得了人工批准
MCP_DESTRUCTIVE_APPROVAL	否	off	auto 会在每次调用破坏性工具前请求人工批准——支持时通过 MCP 宿主，否则通过环回页面。也可设置为 elicitation、loopback
MCP_DESTRUCTIVE_APPROVAL_TIMEOUT	否	120s	环回页面的答复截止时间；elicitation 使用 MCP 宿主/请求的截止时间
MCP_FILE_ROOTS	否	（全部拒绝）	文件操作允许访问的根目录
MCP_AUDIT_ENABLED	否	true	启用审计日志
MCP_AUDIT_LOG_ARGS	否	false	在审计日志中包含工具参数
MCP_AUDIT_FILE	否	—	可选的仅追加 JSONL 审计记录；请使用持久化加密卷
MCP_BIND_HOST	否	127.0.0.1	docker-compose 发布端口所用的主机接口
MCP_AUTH_MODE	否	api-key	api-key，或为 HTTP 部署选择启用外部 oauth
SERVER_PORT	否	8080	HTTP 端口
SERVER_ADDRESS	否	127.0.0.1	内嵌 HTTP 绑定地址；仅在启用 API 密钥或 OAuth 保护时，才设置非环回值

* 在 API 密钥模式下，若未设置密钥，受保护的端点仅接受直接环回请求。来自非环回地址的 /mcp、/actuator/metrics 和 /actuator/prometheus 请求会被拒绝。容器镜像绑定在自身的网络命名空间内，因此，要通过已发布端口或 Docker 网桥访问 MCP，必须配置 API 密钥或 OAuth bearer 保护。

仅供 Compose 使用的便捷变量：

• MCP_UPLOADS_DIR 控制挂载到容器中 /data/uploads 的主机目录。
• KTM_BUILD_DIR 可在本地构建时覆盖 Gradle 的构建目录，而不更改项目默认值。

工具配置文件

MCP_TOOL_PROFILE 会在客户端看到工具之前缩小其公开范围；但不会削弱账户范围限制、允许列表、只读模式、确认、审计或反垃圾控制。reader 始终不会执行更改操作。inbox 包含个人消息、草稿、媒体、联系人和隐私设置；community-admin 包含审核、群组／频道、权限和机器人命令工作流；research 包含范围受限的账户／公开内容发现和阅读。

当前配置文件会显示在 /.well-known/mcp-server.json 和 _manifest 中。有关各工具范围的确切用途，请参阅 TOOL_PROFILES.md。

多账户设置

请为每个标签使用带后缀的环境变量。标签会规范化为小写，且只能包含 a-z、0-9、_ 或 -；它们不会暴露配置文件名称、电话号码或令牌。

TELEGRAM_ACCOUNTS_WORK_API_ID=12345
TELEGRAM_ACCOUNTS_WORK_API_HASH_FILE=/run/secrets/work_api_hash
TELEGRAM_ACCOUNTS_WORK_PHONE_NUMBER=+15551234567

TELEGRAM_ACCOUNTS_PERSONAL_API_ID=12345
TELEGRAM_ACCOUNTS_PERSONAL_API_HASH_FILE=/run/secrets/personal_api_hash
TELEGRAM_ACCOUNTS_PERSONAL_PHONE_NUMBER=+15557654321

TELEGRAM_ACCOUNTS_WORK_PROXY_TYPE=mtproto
TELEGRAM_ACCOUNTS_WORK_PROXY_SERVER=proxy.example.net
TELEGRAM_ACCOUNTS_WORK_PROXY_PORT=443
TELEGRAM_ACCOUNTS_WORK_PROXY_SECRET_FILE=/run/secrets/work_mtproto_secret

除非明确覆盖，否则每个账户都会在平台应用数据目录下获得独立的 TDLib 数据库和下载目录。在多账户模式下，每个 Telegram 工具都必须提供 account 参数。此服务会有意避免将读取请求分发到所有账户：省略该参数时必须以失败关闭，而不能泄露错误账户的数据。调用 list_accounts 可发现经过身份验证的 MCP 客户端可见的标签。

对于远程 MCP 客户端，建议为每个客户端使用一个受限密钥：

MCP_SECURITY_CLIENTS_0_ID=work-agent
MCP_SECURITY_CLIENTS_0_API_KEY_FILE=/run/secrets/work_mcp_key
MCP_SECURITY_CLIENTS_0_ALLOWED_ACCOUNTS_0=work

空的 allowed-accounts 列表允许访问所有已配置的账户；仅将其用于管理员密钥。单账户和受信任的本地部署仍支持旧版 MCP_API_KEY。

API 密钥身份验证

此服务始终支持以下标准请求头格式：

Authorization: Bearer <your-api-key>

或

X-MCP-API-Key: <your-api-key>

如果将 MCP_AUTH_HEADER 设置为其他请求头名称，也会接受该请求头。

通过 mcp.security.clients 配置时，每个经过身份验证的密钥都可以携带一个可选的账户允许列表；在工具访问 TDLib 之前，会强制执行该列表。

公开端点（无需身份验证）：

• GET /actuator/health
• GET /actuator/info
• GET /.well-known/mcp-server.json

该已知描述文件有意保持精简且稳定。它有助于通用安装程序或编排层发现单一用途的连接器，而不会将此服务变成进程内聚合器。

交互式 /auth/** 端点仅在来自回环地址的请求中无需密钥。来自 Docker 网桥、反向代理或专用局域网的请求必须包含已配置的 MCP API 密钥；私有 IP 地址空间不会被视为可信身份。

CSRF 保护适用于会更改状态的请求，包括来自回环地址的请求。只有经过验证的 API 密钥请求头、OAuth Bearer 令牌以及身份验证向导中经过验证的随机数请求头可以免于 CSRF 令牌要求。对于脚本化 HTTP 调用，请配置 MCP API 密钥，并在本地主机上也发送该密钥；不带密钥且没有有效 CSRF 令牌的 POST 请求（包括 /auth/logout 和 /mcp）会返回 403。浏览器身份验证向导会自动处理其随机数。

API 密钥模式未配置密钥时，/mcp 和受保护的 Actuator 端点也遵循同样的失败关闭规则。原始 HTTP 默认绑定到 127.0.0.1；远程部署必须主动更改 SERVER_ADDRESS，并配置 API 密钥或 OAuth。

编排与工具绑定

此代码库是一个 MCP 连接器（工具服务），而不是自主 Agent 运行时。

仅访问 TDLib 并不会让大模型调用 Telegram 工具。要实现端到端行为，必须由外部 MCP 主机、Agent 循环或编排服务完成以下操作：

1. 从此 MCP 服务发现工具架构。
2. 将这些工具架构发送给模型，用于当前轮次。
3. 执行模型请求的工具调用，并将其发送到此 MCP 服务。
4. 将工具结果反馈给模型，直到生成最终助手答复。

没有该编排层时，提示词会作为纯文本生成内容处理，不会执行任何 Telegram 操作。

如果使用多连接器路由器，建议为每个聊天请求明确指定连接器范围，这样 Telegram 对话轮次只会公开 Telegram 工具。

安全模型

Telegram 账号凭据和 TDLib 会话数据都很敏感。在条件允许时，请先使用测试账号，将服务绑定到 localhost，使用足够长的随机 MCP_API_KEY，并保持 MCP_READ_ONLY=true，直到确实需要写入操作。只读模式下，写入工具和会消耗配额的工具不会出现在 MCP 工具列表中，除非你显式启用仅限本地的 download_media 例外（设置 MCP_READ_ONLY_ALLOW_DOWNLOADS=true）；执行保护仍会作为纵深防御机制保留。MCP_CONFIRMATION_REQUIRED=true 会为破坏性操作添加调用方确认步骤，但服务器无法证明 "confirmed": true 是由人设置的：该标志随工具调用一同传递，因此，面对恶意消息的模型可以自行将其设为 true。

MCP_DESTRUCTIVE_APPROVAL=auto 可以弥补这一缺口。每次调用破坏性工具前，都会有人收到询问；回答通过模型无法写入的通道返回，因此，注入的指令可以让模型请求封禁，但无法让它批准封禁。检查会在任何 Telegram 调用之前运行。

问题的显示方式取决于客户端。支持 MCP elicitation 的宿主会显示自己的提示。大多数宿主并不支持——Claude Desktop 声明不具备 elicitation 能力——因此，auto 会回退到由本服务器托管、位于 127.0.0.1 的页面，并在 stderr 上输出链接，你可以在客户端显示服务器输出的位置查看。这个方案并不逊色：链接只能使用一次，受 nonce 保护，只能从你的机器访问，并会在过期后自动拒绝操作。如果你宁可失败，也不愿回退到其他方式，可以强制使用 elicitation 或 loopback。对于你在意的账号，应启用此设置。

loopback 页面由服务器进程提供。在未发布端口的 Docker 网络命名空间中，127.0.0.1 指向容器，而不是你的机器，因此宿主机上的浏览器无法打开该页面。所以，telegram-mcp config --docker ... --writes 会生成 MCP_DESTRUCTIVE_APPROVAL=elicitation，而不是 auto：支持 elicitation 的客户端仍会向你确认；不支持的客户端则会直接拒绝破坏性工具，而不是等待无人能够访问的页面。若要使用 loopback 方式，请在本机运行服务器。

TELEGRAM_ALLOWED_CHAT_IDS 为空时，连接器可以查看所选 Telegram 账号中的所有内容。对于远程部署或面向模型的部署，只要工作流的范围更窄，就应设置明确的聊天白名单。此设置用于控制聊天、消息和文件夹数据，以及面向聊天的副作用；它并非完整的账号沙箱。账号、个人资料和联系人元数据工具仍由账号范围、工具配置文件以及 MCP_TOOL_ALLOW / MCP_TOOL_DENY 控制，因此如有需要，应分别缩小这些范围。

审计摘要和 JSONL 记录不会包含参数值，除非设置 MCP_AUDIT_LOG_ARGS=true；启用后，可识别的凭据字段会被隐藏。将 MCP_AUDIT_FILE 设置为文件路径，可追加写入强制记录的 JSONL，形成持久的本地审计记录。目录会自动创建；符号链接目标会被拒绝，POSIX 文件仅允许其所有者访问。请将记录存放在持久化加密卷上，并采用常规的日志保留和访问控制措施。

服务器绝不会将 API 哈希值、机器人令牌、2FA 密码、身份验证代码或 MCP API 密钥写入磁盘。请通过环境变量或以 *_FILE 挂载的机密提供这些信息。机密文件必须是常规文件（不能是符号链接），大小受限，且不得允许组用户或其他用户写入。请在操作系统或卷层加密 TDLib 会话存储：Windows 使用 BitLocker，macOS 使用 FileVault，Linux 使用 LUKS/fscrypt 或加密卷。

默认情况下，本地状态使用操作系统原生路径：Windows 上为 %LOCALAPPDATA%\\TelegramMcpServer，macOS 上为 ~/Library/Application Support/TelegramMcpServer，Linux 上为 $XDG_DATA_HOME/telegram-mcp-server（或 ~/.local/share/telegram-mcp-server）。配置的相对路径会解析到对应位置下，而不是当前工作目录。 容器镜像将 TELEGRAM_MCP_DATA_DIR=/data/tdlib-data 设为由 compose 卷提供支持。在其他容器编排器下运行多账号服务时，请将同一变量设为加密卷的绝对路径。

工具响应可能包含其他 Telegram 用户编写的文本、链接和文件。在 MCP 客户端或 Agent 中，请将这些内容视为不可信数据；不要让它们覆盖客户端的指令。提示注入策略应由 MCP 宿主或 Agent 负责，因为连接器不会将返回的 Telegram 内容解释为指令。服务仍会强制执行输入大小限制，并支持可选的、由运营者定义的 mcp.guardrails.blocked-patterns 拒绝名单。

transcribe_voice_note 使用 Telegram 自带的 Premium／试用版识别功能。它不会发布新的转录文本消息，也不会将音频上传到第三方服务，但可能会消耗 Telegram 的识别额度，因此在只读模式下不可用，并受到速率限制。

隐私、机器人命令和详细群组权限的写入操作均限定于账号范围、经过审计，并且在 MCP_READ_ONLY=true 时不可用。在 MCP_CONFIRMATION_REQUIRED=true 时，更改群组整体权限、成员权限和管理员权限都需要确认；群组权限更新会保留调用方未指定的所有标志，而管理员权限更新则会有意替换完整权限集，并撤销未指定的权限。

对于远程部署，请在服务前终止 TLS 并限制网络访问。请参阅部署模式和 SECURITY.md。

可用的 MCP 工具

精简任务和持久化导出

工具	描述
inbox_snapshot	受 JSON 字符预算限制的未读收件箱
conversation_bundle	带有独占式旧消息游标的精简对话页面
changes_since	持久化的已观察消息变更，并明确标出覆盖缺口
wait_for_changes	使用可续传游标和可选聊天筛选条件等待已观察到的消息变更
export_job	启动、续传、检查、读取、取消和删除持久化历史记录导出任务

请参阅精简任务和导出和托管式本地守护进程。

每个工具都会提供类型化输出架构，其中包含共用的结构化错误变体。

下方按组列出了完整工具清单。实际使用时，建议从工具配置入手，而不是一次启用全部工具。

显示全部 116 个工具

### 消息（30 个工具）

工具	描述
get_history	获取聊天历史记录（最近的消息）
get_messages	按 ID 获取特定消息
search_messages	搜索特定聊天中的消息
search_global	搜索所有聊天中的消息
send_message	发送文本消息，可选择使用 HTML/Markdown 和持久化幂等键；请参阅 投递恢复
get_send_operation	按目的地和幂等键读取账户范围内的投递回执
reply_to_message	回复特定消息
edit_message	编辑现有消息
delete_message	删除消息（具有破坏性，需确认）
forward_message	在聊天之间转发消息
pin_message	在聊天中置顶消息
unpin_message	取消置顶消息
get_pinned_messages	获取聊天中的所有置顶消息
mark_as_read	将消息标记为已读
send_reaction	为消息添加表情回应（需确认）
remove_reaction	移除消息的表情回应（需确认）
get_message_reactions	获取回应数量；在 Telegram 允许时列出发送者
create_poll	发送投票（匿名或公开，可单选或多选）
vote_poll	使用从 0 开始的选项索引参与投票
close_poll	永久关闭投票（具有破坏性，需确认）
get_message_viewers	列出小型群组中外发消息的已读回执
get_message_context	获取目标消息前后的 N 条消息
list_inline_buttons	检查消息上的内联键盘按钮
press_inline_button	按索引或标签点击内联按钮（需确认）
message_from_link	将 t.me 消息链接解析为实际消息
get_message_link	为消息或媒体相册创建可分享的 t.me 链接
list_scheduled_messages	列出聊天的排队消息
schedule_message	将文本消息加入队列，并安排在未来的 ISO 时间或 Unix 时间戳发送
reschedule_message	更改排队消息的发送时间
cancel_scheduled_message	取消排队消息（具有破坏性，需确认）

聊天（45 个工具）

工具	描述
list_chats	列出所有聊天，可按类型或未读状态筛选
get_chat	获取详细的聊天信息（成员、描述）
get_participants	获取群组或频道的成员
create_group	创建新的普通群组
create_supergroup	创建私人超级群组，可选择启用论坛功能
invite_to_group	邀请用户加入群组
leave_chat	退出聊天（破坏性操作，需要确认）
ban_user	封禁聊天中的用户（破坏性操作）
unban_user	解除对用户的封禁
promote_admin	将用户提升为管理员
demote_admin	将管理员降为普通成员
edit_chat_title	更改聊天标题
set_chat_description	替换群组、超级群组或频道的描述
set_slow_mode	设置超级群组的慢速模式延迟（启用时需要确认模式）
edit_chat_photo	设置或替换聊天照片（写入、文件安全）
delete_chat_photo	移除聊天照片（破坏性操作，需要确认）
archive_chat	归档聊天
unarchive_chat	取消归档聊天
mute_chat	静音聊天通知
unmute_chat	取消静音聊天通知
list_topics	列出超级群组中的论坛主题
create_topic	在已启用主题功能的超级群组中创建论坛主题
edit_forum_topic	重命名论坛主题，并可选择更新其自定义表情图标
close_forum_topic	关闭论坛主题
reopen_forum_topic	重新打开已关闭的论坛主题
set_forum_topics_enabled	在超级群组中启用或停用论坛主题
create_channel	创建新频道或超级群组，可选择启用论坛功能（破坏性操作，需要确认）
get_invite_link	为聊天生成邀请链接
list_invite_links	列出当前账号为聊天创建的邀请链接
revoke_invite_link	撤销邀请链接（破坏性操作，需要确认）
join_chat_by_link	通过邀请链接加入聊天（破坏性操作，需要确认）
subscribe_public_channel	通过用户名订阅公开频道（幂等）
get_admins	列出聊天的管理员
get_banned_users	列出聊天中被封禁的成员
search_public_chats	搜索 Telegram 公开聊天的全局目录
get_recent_actions	获取超级群组或频道的管理员事件日志
list_chat_folders	列出 TDLib 已知的账号聊天文件夹
get_chat_folder	查看某个文件夹的完整匹配规则
configure_chat_folder	创建文件夹配置或完整替换现有配置
delete_chat_folder	删除文件夹，但不退出其中的聊天（破坏性操作，需要确认）
reorder_chat_folders	按指定的完整 ID 顺序重新排列文件夹
get_group_permissions	获取默认群组权限标志
set_group_permissions	更新选定的默认群组权限标志（启用时需要确认模式）
set_member_permissions	限制或恢复单个成员的权限，但不封禁该成员（启用时需要确认模式）
set_admin_rights	替换某个成员的详细管理员权限集合（启用时需要确认模式）

configure_chat_folder 会刻意发送完整的 TDLib 文件夹定义： 提供 folder_id 时，它会替换该文件夹的规则，而不会悄悄合并未知状态。list_chat_folders 的数据来自 TDLib 的账号文件夹更新流；如需获取已知文件夹 ID 的完整规则，请调用 get_chat_folder。定时任务的时间戳可使用未来的 ISO-8601 时刻或 Unix 纪元秒数；Telegram 会对重复计划应用任何产品或账号限制。

账号隐私与机器人命令（4 个工具）

工具	描述
get_privacy_settings	获取某项账号隐私设置的完整规则
set_privacy_settings	使用明确的用户／聊天例外项替换某项隐私规则集
get_bot_commands	获取适用于指定语言和受众范围的机器人命令菜单
set_bot_commands	替换机器人命令菜单；Telegram 不允许用户账号执行此操作

set_privacy_settings 会有意替换所选设置的完整规则集。它支持基础受众范围以及明确指定的用户、聊天、机器人和 Premium 用户例外项；不会映射 TDLib 的所有原始设置。机器人命令工具支持 Telegram 默认、所有私聊、所有群组、所有管理员、指定聊天、指定聊天的管理员以及指定聊天的成员范围。

用户与联系人（16 个工具）

工具	描述
get_me	获取当前用户资料
list_contacts	列出通讯录中的联系人
resolve_username	将 @username 解析为数字 ID
add_contact	将用户添加到联系人
delete_contact	移除联系人（破坏性操作）
block_user	屏蔽用户（破坏性操作）
unblock_user	解除屏蔽用户
update_profile	更新名字、姓氏和／或简介
set_profile_photo	上传并设置头像（写入操作，文件安全）
delete_profile_photo	删除当前头像（破坏性操作，需要确认）
get_user_photos	获取用户的头像
search_contacts	按名称搜索本地联系人列表
get_blocked_users	列出被屏蔽的用户／发送者
get_user_status	获取用户的在线／最后上线状态
get_last_interaction	获取与联系人的最近一条往来消息
get_common_chats	列出与用户共同加入的群组和频道

媒体（7 个工具）

工具	描述
get_media_info	获取消息中媒体的元数据
download_media	将媒体下载到账号缓存（只读模式下需要设置 MCP_READ_ONLY_ALLOW_DOWNLOADS=true）
send_file	上传并发送文件
send_voice	向聊天发送语音消息（OGG/Opus）（写入操作，文件安全）
transcribe_voice_note	请求 Telegram 对语音消息进行原生转录（Premium／试用配额；不会发送新消息）
send_sticker	向聊天发送贴纸（WEBP/TGS/WEBM）（写入操作，文件安全）
get_sticker_sets	列出已安装的常规贴纸包

草稿（3 个工具）

工具	描述
save_draft	在聊天中保存草稿消息（可选作为回复）
get_drafts	汇总所有存在非空草稿的聊天
clear_draft	清除聊天中的草稿

公开搜索（3 个工具）

工具	描述
discover_public_chats	发现公开聊天，可选择限制为运营者允许列表中的对象
search_public_messages	使用客户端提供的多语言查询变体搜索多个聊天
export_chat_history	导出有限范围的聊天记录，供本地分析

search_public_messages 不会猜测区域设置，也不会应用隐藏的产品术语表。请为 query_variants 提供翻译、同义词、俚语或可能的拼写错误。在 MCP 主机或产品编排器中解读描述和置顶消息；在这些位置可配置特定区域设置的推广和触达政策，而无需将其与 Telegram 传输层耦合。

元信息（3 个工具）

工具	描述
_manifest	返回精简的自我描述和分组工具清单，其中 serverVersion 包含当前运行的版本
list_accounts	列出经身份验证的 MCP 客户端可见的账号路由标签
register_internal_chat	将运营者控制聊天标记为内部反垃圾信息上下文（破坏性操作，需要确认——此操作会放宽该聊天的速率限制）

## 如何添加新工具

1. 在 src/main/kotlin/dev/telegrammcp/server/tool/ 中创建一个新类：

@Component
class MyNewTool(
    private val telegramService: TelegramClientService,
    private val guardrailService: GuardrailService,
    private val objectMapper: ObjectMapper,
    private val meterRegistry: MeterRegistry,

) : McpToolHandler {

    override fun definition(): McpSchema.Tool = ToolSupport.definition(
        "my_new_tool",
        "Description of what this tool does",
        INPUT_SCHEMA,
        objectMapper,
    )

    override fun execute(
        exchange: McpSyncServerExchange,
        arguments: Map<String, Any>,
    ): McpSchema.CallToolResult {
        // Your logic here
    }
}

2. 就这样。工具会在启动时自动发现并注册。McpConfig 会自动为绑定账户的工具添加安全的 account 选择器。

项目结构

src/main/kotlin/dev/telegrammcp/server/
├── TelegramMcpApplication.kt          # Entry point
├── api/                                # Loopback-only interactive auth wizard endpoints
├── auth/                               # TDLib auth orchestration & runtime credentials
├── cli/                                # serve / auth / session / version commands
├── client/                             # Telegram client abstraction
│   ├── TelegramClientService.kt        # Telegram capability interface
│   ├── TdLibClientService.kt           # TDLib implementation
│   ├── TdLibConfig.kt                  # TDLib bean configuration & lifecycle
│   ├── TelegramAccountRegistry.kt      # Isolated multi-account routing
│   └── FallbackClientConfig.kt         # Fallback when TDLib unavailable
├── config/                             # Typed configuration properties & MCP wiring
│   ├── TdLibProperties.kt              # TDLib config (api, auth, database, session, proxy)
│   ├── McpSecurityProperties.kt
│   ├── ServerModeProperties.kt
│   └── McpConfig.kt                    # Tool registration, profiles, account selector
├── controller/                         # Well-known descriptor & OAuth metadata endpoints
├── model/                              # Domain models
│   ├── TelegramModels.kt
│   ├── EntityIdentifier.kt             # Sealed hierarchy: NumericId / Username / PhoneNumber
│   └── UserInfo.kt                     # UserInfo + ContactInfo
├── security/                           # Spring Security, API keys, account scoping
│   ├── SecurityConfig.kt
│   ├── ApiKeyAuthFilter.kt
│   ├── AccountAccessPolicy.kt
│   └── SecretResolver.kt               # *_FILE mounted-secret validation
├── service/                            # Business logic
│   ├── EntityResolverService.kt        # @username / +phone / ID resolution
│   ├── GuardrailService.kt             # Input limits & chat access
│   ├── OperationGuardService.kt        # Read-only & confirmation modes
│   ├── ToolSurfacePolicy.kt            # Tool profiles & allow/deny filters
│   ├── AntiSpamGuardService.kt         # Rate limits, daily caps, dedup
│   ├── AuditService.kt                 # Audit logging
│   └── FileSecurityService.kt          # File upload security
├── tool/                               # MCP Tools (auto-discovered)
│   ├── McpToolHandler.kt               # Tool interface
│   ├── message/                        # 30 message tools
│   ├── chat/                           # 49 chat, folder, permission & privacy tools
│   ├── user/                           # 16 user/contact tools
│   ├── media/                          # 7 media tools
│   ├── draft/                          # 3 draft tools
│   ├── research/                       # 3 bounded public-search tools
│   └── meta/                           # 3 manifest/account tools
├── util/                               # StructuredLogger, TextFormatter, MdcFilter
└── exception/                          # McpExceptions, GlobalExceptionHandler

测试

# Unit tests
./gradlew test

# Specific test class
./gradlew test --tests "dev.telegrammcp.server.service.GuardrailServiceTest"

贡献与支持

提交拉取请求前，请阅读 CONTRIBUTING.md；如需了解发布历史，请查看 CHANGELOG.md。如要报告漏洞，请勿 公开提交问题；请遵循 SECURITY.md 中的指引。社区准则见 CODE_OF_CONDUCT.md。

指标

启用 Prometheus 后，可通过 /actuator/prometheus 获取指标：

• mcp.tool.execution — 按工具名称统计的工具执行时长
• mcp.audit.operations — 按工具、类别和结果统计的审计计数器
• telegram.api.rate_limited — 限流器拒绝次数
• telegram.api.circuit_open — 熔断器打开事件
• 标准 Spring Boot / Micrometer HTTP 指标

许可证

Apache License 2.0