内容
# Telegram MCP 服务器
[](LICENSE)
[](https://github.com/tolboy/telegram-mcp-tdlib/actions/workflows/ci.yml)
[](https://github.com/tolboy/telegram-mcp-tdlib/actions/workflows/security.yml)
[](https://github.com/tolboy/telegram-mcp-tdlib/releases/latest)
**适用于真实账户的 Telegram MCP 服务器 - 默认安全，由 TDLib 驱动，生产就绪。**
本地优先的 [模型上下文协议](https://modelcontextprotocol.io/) 服务器，为 AI 代理提供真实的 Telegram 账户访问权限，而无需提供账户密钥。它以只读模式启动，隐藏写入工具，直到您选择启用，并通过 **STDIO** 为桌面客户端或 **Streamable HTTP** 在 `/mcp` 上为托管部署运行。
### 为什么选择这个？
- **默认安全** - 以只读模式启动，带有小型 `inbox` / `reader` 配置文件；写入和消耗配额的工具在您启用之前对模型**隐藏**，而不仅仅是阻止。
- **真实用户账户，而不仅仅是机器人** - 构建在 **TDLib** （通过 tdlight-java）上，因此代理可以读取和操作您的实际账户，而不仅仅是 Bot API 子集。
- **隔离多账户** - 每个账户都有自己的会话，强制选择和范围 API 密钥；读取永远不会扩展到多个账户。
- **两种传输方式** - STDIO 用于桌面客户端，Streamable HTTP 用于托管服务。
- **无需安装 JDK** - 适用于 Windows、Linux x64/ARM64 和 Apple 硅 macOS 的运行时包含发布包，带有校验和，SBOM 和签名容器摘要。
> 图片是说明性的模拟；真实的屏幕截图正在制作中。
## 安全的首运行
运行时包含的发布包不需要 JDK、Gradle、Git、Python 或 Node.js。请为首次运行使用测试账户。
**1. 安装** （macOS Apple 硅 / Linux 使用 Homebrew）：
```bash
brew install --formula https://github.com/tolboy/telegram-mcp-tdlib/releases/latest/download/telegram-mcp.rb
```
Windows 使用 Scoop：
```powershell
scoop install https://github.com/tolboy/telegram-mcp-tdlib/releases/latest/download/telegram-mcp.json
```
**2. 登录** 通过二维码扫描 - 一次性代码从不触及您的 shell 历史记录：
```bash
telegram-mcp auth --method qr
```
**3. 通过 STDIO 提供一个小型只读界面**:
```bash
MCP_TOOL_PROFILE=inbox MCP_READ_ONLY=true telegram-mcp serve --transport stdio
```
现在，将 AI 客户端指向它（如下所示），并尝试第一个不能更改任何内容的提示：
> “总结我最近的 20 次对话。不要发送或修改任何内容。”
在此模式下，写入和消耗配额的工具完全从工具列表中缺失，因此模型没有可破坏的内容调用。切换到 `MCP_READ_ONLY=false` 仅在您审查过界面后；默认情况下，破坏性操作仍需要确认。
## 连接您的客户端
STDIO 是桌面客户端的低摩擦路径。最小入口：
```json
{
"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` （设置 → 开发者 → 编辑配置），然后重启应用程序。
- **Cursor** - 将其添加到 `~/.cursor/mcp.json` （或设置 → MCP → 添加）。
- **VS Code** - 使用 `.vscode/mcp.json` ； VS Code 将顶级键命名为 `servers` 而不是 `mcpServers` ，否则条目相同。
对于托管的 HTTP 部署而不是 STDIO：
```bash
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](docs/CLI_AND_STDIO.md)，[交互式身份验证](docs/INTERACTIVE_AUTH.md)，和 [客户端兼容性](docs/MCP_CLIENT_COMPATIBILITY.md)，获取确切的平台/客户端变体。
## 配方
复制粘贴配置和提示，适用于真实任务，每个任务都具有可以完成任务的最小工具界面：
[总结您的收件箱](docs/recipes/summarize-inbox.md)，
[查找丢失的消息](docs/recipes/find-lost-message.md)，
[研究公共群组](docs/recipes/research-public-groups.md)，
[只读社区健康检查](docs/recipes/community-review-readonly.md)，
和 [在不发送的情况下草拟回复](docs/recipes/safe-draft-reply.md) —
索引在 [docs/recipes](docs/recipes/README.md)。
## 比较
大多数 Telegram MCP 服务器包装 Bot API 或 Telethon 用户会话，并一次性向模型公开所有功能。此项目针对**您关心的真实账户**，安全地连接代理：
| 维度 | 此服务器 | 典型的 Telethon / Bot-API MCP 服务器 |
|---|---|---|
| 账户访问 | 通过 TDLib （tdlight-java） 的真实用户账户 | 通常仅限机器人，或单个 Telethon 用户会话 |
| 默认姿态 | 只读；**隐藏**写入/配额工具，直到启用 | 通常从一开始就公开所有工具 |
| 多账户 | 隔离会话，强制选择，范围密钥，**无跨账户读取扩展** | 单账户，或隐含扩展 |
| 传输 | STDIO **和** Streamable HTTP `/mcp` | 通常仅限 STDIO |
| 防护措施 | 确认门控，审计日志，防垃圾邮件限制，聊天允许列表，不受信任内容标记 | 最小 |
| 分发 | 签名运行时包（无 JDK），SBOM + 来源，GHCR 镜像 | 通过 pip/npx 源安装 |
更完整的架构比较（TDLib vs Telethon vs Bot API，以及为什么“隐藏，而不是阻止”很重要）在 [docs/COMPARISON.md](docs/COMPARISON.md) 中。针对领先的公共服务器的详细基准测试（包括故意拒绝的功能（原始 MTProto 出口， 所有权转移，批量联系人导出））在 [PUBLIC_BENCHMARK_AND_ROADMAP.md](docs/PUBLIC_BENCHMARK_AND_ROADMAP.md) 中。
## 工具配置文件
您不会在第一天就公开 110 个工具。`MCP_TOOL_PROFILE` 在客户端**看到之前**缩小广告界面，没有削弱账户范围、只读模式、确认、审计或防垃圾邮件：
| 配置文件 | 界面 |
|---|---|
| `reader` | 始终非突变 - 安全的第一印象 |
| `inbox` | 个人消息，草稿，媒体，联系人，隐私 |
| `community-admin` | 审核，群组/频道，权限，机器人命令 |
| `research` | 有界账户/公共发现和阅读 |
| `all` | 完整的库存（有意选择） |
参见 [TOOL_PROFILES.md](docs/TOOL_PROFILES.md)，获取每个界面的确切意图。
## 功能
- **110 个 MCP 工具** - 消息，投票，阅读回执，计划发送，聊天，文件夹，邀请链接管理，联系人，媒体，草稿，隐私，机器人命令，详细的群组权限，配置文件，搜索和账户路由。
- **通过 tdlight-java 的 TDLib** - 真实用户账户，而不仅仅是 Bot API。
- **隔离的多账户模式** - 独立会话，强制账户选择和可选的每个密钥账户范围，无跨账户读取扩展。
- **默认安全** - 只读工具界面，破坏性操作的确认模式和任务聚焦的配置文件（`reader` / `inbox` / `community-admin` / `research` / `all`）。
- **两种传输方式** - STDIO 用于桌面客户端，Streamable HTTP `/mcp` （Spring AI 2.0 / MCP SDK 2.0），带有 API 密钥身份验证。
- **防护措施** - 审计日志，防垃圾邮件（通过 Resilience4j 速率限制器（30 req/s）和断路器），聊天允许列表，提示注入模式和不受信任的内容标记。
- **可观察性** - Micrometer 指标，Prometheus 端点和带有 MDC 的结构化 JSON 日志（`traceId` ， `sessionId` ， `toolName` ）。
- **已验证的运行时包含发布包** - Windows x64，Linux x64/ARM64 和 Apple 硅 macOS 包，带有校验和，SBOM 和签名容器摘要 - 无需 JDK。
<details>
<summary>更多功能</summary>
- **实体解析** - 透明地解析 `@username` ， `+phone` 或数字 ID。
- **MCP 行为注释** - 每个广告工具声明只读，破坏性，重试和开放世界提示，以实现更安全的客户端 UX。
- **结构化，标记输出** - 向后兼容的 JSON 文本和 `structuredContent` ； Telegram 控制的字段明确为不受信任，演示控制 Unicode 被转义。
- **基于主机的发现** 通过 `/.well-known/mcp-server.json` 为安装程序，桌面主机和服务管理器。
- **文件安全服务** 用于安全媒体上传； **执行器** 健康/信息/指标； **优雅关闭** ，具有可配置的超时。
- **多阶段 Docker** 构建 + docker-compose，带有开发热重载。
- **运行时包含的应用镜像** - 支持的发布存档包括它们自己的 Java 运行时，并通过发布前进行实际的 STDIO 握手。
- **离线会话医生** - 检查配置的 TDLib 状态路径和锁定可用性，而无需启动 TDLib 或打印机密。
- **干净的架构** - 配置 / 模型 / 客户端 / 服务 / 工具 / 安全 / 实用程序 / 异常。
- **语言中立的公共搜索** - 调用者传递同义词，翻译和拼写变体，以任何语言；产品特定的策略解释保留在 MCP 主机中。
</details>
## 技术栈
| 组件 | 版本 |
| --- | --- |
| Java | 25 |
| Kotlin | 2.4.0 |
| Spring Boot | 4.1.0 |
| Spring AI MCP | 2.0.0 |
| MCP Java SDK | 2.0.0 |
| TDLib （tdlight） | 3.5.3+td.1.8.65 |
| Gradle | 9.6.1 |
| 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. 克隆和配置
```bash
git clone https://github.com/tolboy/telegram-mcp-tdlib.git
cd telegram-mcp-tdlib
cp .env.example .env
# 编辑 .env - 设置 TDLIB_API_ID，TDLIB_API_HASH，TDLIB_PHONE_NUMBER/TDLIB_BOT_TOKEN 和 MCP_API_KEY
```
在 Windows PowerShell 上，使用 `Copy-Item .env.example .env` 代替 `cp` 。
### 2. 在本地运行
```bash
./gradlew bootRun
```
服务器启动在 `http://localhost:8080` 。其 MCP Streamable HTTP 端点是 `http://localhost:8080/mcp` 。
### 您的第一个 60 秒
1. 在客户端中添加远程 **Streamable HTTP** MCP 服务器，网址为 `http://127.0.0.1:8080/mcp` 和 `Authorization: Bearer <MCP_API_KEY>` 。
Claude Desktop、Cursor、VS Code 和 Inspector 的稳定连接数据保存在 [MCP_CLIENT_COMPATIBILITY.md](docs/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 运行
```bash
docker compose up --build
```
Compose 堆栈在 `tdlib-data` 卷中保留 TDLib 会话数据，在 `telegram-downloads` 中下载，在 `${MCP_UPLOADS_DIR:-./docker-data/uploads}` 中将 `./docker-data/uploads` 挂载到容器中，作为 `/data/uploads` 用于上传/下载工具。
默认情况下，Compose 通过 `MCP_BIND_HOST` 将服务绑定到 `127.0.0.1` ，以避免在 LAN 上意外暴露本地盒/开发人员场景。
开发模式与热重载：
```bash
docker compose --profile dev up telegram-mcp-dev
```
使用 Prometheus 监控：
```bash
docker compose --profile monitoring up
```
生产注意：在容器前面终止 TLS （反向代理，入口或负载均衡器）。 API 密钥不应在受信任的本地开发网络外部通过纯文本 HTTP 传输。
本地安装与远程/VPS 暴露的部署指南在 `docs/DEPLOYMENT_MODES.md` 中记录。
多服务器 MCP 主机或安装程序的连接器发现记录在 `docs/CONNECTOR_DISCOVERY.md` 中。
客户端兼容性，便携式 JSON-Schema 配置文件和 Streamable HTTP 烟雾测试记录在 [MCP_CLIENT_COMPATIBILITY.md](docs/MCP_CLIENT_COMPATIBILITY.md) 中。
离线安全的 TDLib 会话检查和清除记录在 [SESSION_MAINTENANCE.md](docs/SESSION_MAINTENANCE.md) 中。
与领先的公共 Telegram MCP 服务器的比较以及优先的后续工作记录在 [PUBLIC_BENCHMARK_AND_ROADMAP.md](docs/PUBLIC_BENCHMARK_AND_ROADMAP.md) 中。
## 版本
每次拉取请求和推送到 `master` 时，CI 都会运行。签名发布是 `vX.Y.Z` 形式的 Git 标签；发布工作流构建并发布相应的 GHCR 镜像标签（`latest` ， `X.Y.Z` ， `X.Y` 和不可变的 `sha-<commit>` ），以及 Windows x64，Linux x64/ARM64 和 macOS ARM64 的检查发布包。公共发布包括运行 JAR 的 SPDX SBOM，GitHub 来源证明和发布资产的密钥库签名，以及容器摘要的密钥库签名和来源。参见 [发布包验证](docs/RELEASE_BUNDLES.md#supply-chain-verification)。
使用具体的 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 资源服务器模式和运行时包含的发布镜像。完整的历史记录在 [CHANGELOG.md](CHANGELOG.md) 中。
> 当前的 TDLight 原生发布版发布了一个 Apple 硅 macOS 二进制文件，但没有 Intel macOS 分类器。该服务器在 JVM/路径级别支持 Intel macOS，但 TDLib 支持的 Telegram 访问在该平台上需要上游原生包才能运行。
要为当前匹配的平台创建运行时包含的应用镜像：
```powershell
./scripts/package-app-image.ps1 -Version <version> -Target windows-x64 -OutputDirectory release-assets
```
构建验证实际的 `BOOT-INF/lib` 内容，启动器报告的版本和实时 STDIO 握手。参见 [RELEASE_BUNDLES.md](docs/RELEASE_BUNDLES.md) 获取目标矩阵。
```bash
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` | 否† | — | 机器人模式的机器人令牌 |
| `TDLIB_BOT_TOKEN_FILE` | 否 | — | 机器人令牌的替代秘密文件 |
| `TDLIB_2FA_PASSWORD` | 否 | — | 2FA 密码（用于无头启动时提供） |
| `TDLIB_2FA_PASSWORD_FILE`| 否 | — | 2FA 密码的替代秘密文件 |
| `TDLIB_AUTH_CODE` | 否 | — | 一次性登录代码（用于无头首次运行时提供） |
| `TDLIB_AUTH_CODE_FILE` | 否 | — | 一次性登录代码的替代秘密文件 |
| `TDLIB_DATA_DIR` | 否 | 操作系统应用程序数据目录 | 会话数据库目录 |
| `TDLIB_DOWNLOADS_DIR` | 否 | （在数据目录下） | 已下载媒体文件目录 |
| `TDLIB_LOG_VERBOSITY` | 否 | `1` | TDLib 原生日志详细程度（0–10） |
| `TDLIB_SYSTEM_LANGUAGE_CODE` | 否 | `zh` | 为 Telegram 会话报告的语言代码 |
| `TDLIB_DEVICE_MODEL` | 否 | `Telegram MCP 服务器` | 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 请求；通常保留 `false` 以便 CONNECT |
\* 在启用 TDLib 集成时需要。
† 必须设置其中一个：`TDLIB_PHONE_NUMBER` 或 `TDLIB_BOT_TOKEN`。
非交互式身份验证：在全新容器中，设置 `TDLIB_AUTH_CODE` 一次（如果启用了 2FA，还需要 `TDLIB_2FA_PASSWORD`）。会话持久化到 `TDLIB_DATA_DIR` 后，重启时不再需要它们。每个直接秘密设置都有一个互斥的 `*_FILE` 替代方案，用于 Docker/Podman/Kubernetes 秘密挂载。
对于本地首次登录，不将一次性代码放入环境变量中，请使用手机/代码或二维码流程，详见 [INTERACTIVE_AUTH.md](docs/INTERACTIVE_AUTH.md)。`TDLIB_DEVICE_MODEL` 和 `TDLIB_SYSTEM_LANGUAGE_CODE` 控制在 Telegram **设置 → 设备** 中显示的可识别会话身份。
静态加密说明：`SimpleTelegramClient`（tdlight-java）不公开 TDLib 数据库加密密钥。对于生产环境，请在文件系统级别加密 `TDLIB_DATA_DIR` 卷（LUKS、FileVault、EFS），而不是依赖库级标志。额外的 `use-file-database`、`use-chat-info-database`、`use-message-database` 开关可在 [TdLibProperties.kt](src/main/kotlin/dev/telegrammcp/server/config/TdLibProperties.kt) 中找到。
### Telegram 代理
服务器在登录前配置 TDLib 自己的代理，因此它涵盖了初始身份验证和正常的 Telegram 流量。请使用以下完整的配置之一；不完整或无效的代理设置会导致启动失败，账户无法连接。
```dotenv
# SOCKS5 代理，支持可选的用户名/密码身份验证
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（设置 HTTP_ONLY=false 以将所有 TDLib 流量路由到它）
# TDLIB_PROXY_TYPE=http
# TDLIB_PROXY_SERVER=proxy.example.net
# TDLIB_PROXY_PORT=3128
# TDLIB_PROXY_HTTP_ONLY=false
# MTProto（必须直接或通过 *_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` | 否 | — | 机器人用户名（用于日志记录） |
| `TELEGRAM_ALLOWED_CHAT_IDS`| 否 | （所有聊天允许） | 允许的聊天 ID 列表 |
| `MCP_API_KEY` | 是* | — | MCP 端点身份验证的 API 密钥 |
| `MCP_API_KEY_FILE` | 否 | — | `MCP_API_KEY` 的替代秘密文件 |
| `MCP_AUTH_HEADER` | 否 | `Authorization` | API 密钥的头部名称 |
| `MCP_READ_ONLY` | 否 | `true` | 在显式禁用之前阻止所有写入/变异工具 |
| `MCP_TOOL_PROFILE` | 否 | `all` | `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_FILE_ROOTS` | 否 | （拒绝所有） | 文件操作的允许根目录列表 |
| `MCP_AUDIT_ENABLED` | 否 | `true` | 启用审计日志 |
| `MCP_AUDIT_LOG_ARGS` | 否 | `false` | 在审计日志中包含工具参数 |
| `MCP_BIND_HOST` | 否 | `127.0.0.1` | Docker Compose 端口发布的宿主接口 |
| `MCP_AUTH_MODE` | 否 | `api-key` | `api-key` 或选择外部 `oauth` 以进行 HTTP 部署 |
| `SERVER_PORT` | 否 | `8080` | HTTP 端口 |
\* 当为空时，身份验证被禁用（仅限本地开发）。
仅适用于 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](docs/TOOL_PROFILES.md)。
### 多账户设置
对每个标签使用后缀环境变量。标签规范化为小写，并且必须仅包含 `a-z`、`0-9`、`_` 或 `-`；它们永远不会公开配置文件名称、电话号码或令牌。
```dotenv
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 客户端，每个客户端优先使用一个范围限定的密钥：
```dotenv
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 空间不被视为受信任的身份。
## 编排和工具绑定
此存储库是一个 MCP 连接器（工具服务器），而不是自治代理运行时。
仅 TDLib 访问权限不足以调用 Telegram 工具。为了实现端到端行为，外部 MCP 主机、代理循环或编排服务必须：
1. 从此 MCP 服务器发现工具模式。
2. 将这些工具模式发送到模型以用于当前回合。
3. 对模型请求的工具调用执行此 MCP 服务器。
4. 将工具结果反馈回模型，直到产生最终的助手答案。
没有编排层，提示将被处理为纯文本生成，并且不会执行任何 Telegram 操作。
如果使用多连接器路由器，请为每个聊天请求使用显式连接器范围限定，以便 Telegram 转折仅公开 Telegram 工具。
## 安全模型
Telegram 账户凭证和 TDLib 会话数据是敏感的。在可能的情况下，请从测试账户开始，将服务绑定到 localhost，使用长随机 `MCP_API_KEY`，并在您故意需要写入时保持 `MCP_READ_ONLY=true`。在只读模式下，写入和消耗配额的工具从 MCP 工具列表中消失；执行防护仍然作为纵深防御。使用 `MCP_CONFIRMATION_REQUIRED=true` 以增加对破坏性操作的显式确认步骤。
服务器永远不会将 API 哈希、机器人令牌、2FA 密码、身份验证代码或 MCP API 密钥写入磁盘。请通过环境变量或挂载的秘密文件提供它们。秘密文件必须是常规文件（不是符号链接），大小有限制，并且可能不允许组或其他用户写入。加密 TDLib 会话存储在操作系统/卷级别：Windows 上的 BitLocker、macOS 上的 FileVault 和 Linux 上的 LUKS/fscrypt 或加密卷。
本地状态默认使用原生 OS 路径：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 客户端或代理中不要让它覆盖客户端的指令。提示注入策略属于 MCP 主机或代理，因为连接器不会将返回的 Telegram 内容解释为指令。服务器仍然强制执行输入大小限制并支持可选的操作员定义的 `mcp.guardrails.blocked-patterns` 拒绝列表。
`transcribe_voice_note` 使用 Telegram 自己的高级/试用识别功能。它永远不会发布新的转录消息或将音频上传到第三方服务，但它可以消耗 Telegram 识别额度，因此在只读模式下被阻止并受到速率限制。
权限、机器人命令和群组权限写入是账户范围内的、经过审计的，并且在 `MCP_READ_ONLY=true` 时缺失。群组范围、成员和管理员权限更改在 `MCP_CONFIRMATION_REQUIRED=true` 时需要确认；群组权限更新保留调用者省略的每个标志，而管理员权限更新故意替换完整的集合并撤销省略的权限。
对于远程部署，请在服务前终止 TLS 并限制网络访问。请参阅 [部署模式](docs/DEPLOYMENT_MODES.md) 和 [SECURITY.md](SECURITY.md)。
## 可用的 MCP 工具
下面对工具进行分组。在实践中，您从 [工具配置文件](#tool-profiles) 开始，而不是一次性启用所有工具。
<details>
<summary><b>显示所有 110 个工具</b></summary>
### 消息（29 个工具）
| 工具 | 描述 |
|------|-------------|
| `get_history` | 检索聊天历史记录（最近的消息） |
| `get_messages` | 按 ID 获取特定消息 |
| `search_messages` | 在特定聊天中搜索消息 |
| `search_global` | 跨所有聊天搜索消息 |
| `send_message` | 发送带有可选 HTML/Markdown 的文本消息 |
| `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` | 列出消息上的所有反应及其发送者 |
| `create_poll` | 发送投票（匿名或公开，单选或多选） |
| `vote_poll` | 按 0-based 选项索引投票 |
| `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 的账户文件夹更新流中填充；
调用 `get_chat_folder` 获取已知文件夹 ID 的完整规则。计划时间戳接受未来的 ISO-8601 时间或 Unix 时间戳秒；
Telegram 将任何产品/账户限制应用于重复计划。
### 账户隐私和机器人命令 (4 个工具)
| 工具 | 描述 |
|------|-------------|
| `get_privacy_settings` | 获取一个账户隐私设置的完整规则 |
| `set_privacy_settings` | 用显式用户/聊天例外替换一个隐私规则集 |
| `get_bot_commands` | 获取机器人命令菜单，适用于语言和受众范围 |
| `set_bot_commands` | 替换机器人命令菜单；Telegram 拒绝用户账户的命令 |
`set_privacy_settings` 有意替换所选设置的完整规则集。
它支持基本受众以及显式用户、聊天、机器人和高级用户例外；
它不镜像每个原始 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` | 下载媒体到本地文件（在只读模式下隐藏） |
| `send_file` | 上传并发送文件 |
| `send_voice` | 向聊天发送语音笔记（OGG/Opus）（写入，文件安全） |
| `transcribe_voice_note` | 请求 Telegram 对语音消息的原生转录（高级/试用配额；不会发送新消息） |
| `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` | 返回紧凑的自我描述和分组的工具清单 |
| `list_accounts` | 列出通过身份验证的 MCP 客户端可见的账户路由标签 |
| `register_internal_chat` | 将操作员控制聊天标记为内部反垃圾邮件上下文（破坏性，需要确认 - 它放松了该聊天的速率限制） |
## 如何添加新工具
1. 在 `src/main/kotlin/dev/telegrammcp/server/tool/` 中创建一个新类：
```kotlin
@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 # 入口点
├── api/ # 仅限 Loopback 的交互式身份验证向导端点
├── auth/ # TDLib 身份验证编排和运行时凭证
├── cli/ # 提供 / auth / session / version 命令
├── client/ # Telegram 客户端抽象
│ ├── TelegramClientService.kt # Telegram 功能接口
│ ├── TdLibClientService.kt # TDLib 实现
│ ├── TdLibConfig.kt # TDLib 配置（api，auth，database，session，proxy）
│ ├── TelegramAccountRegistry.kt # 隔离的多账户路由
│ └── FallbackClientConfig.kt # TDLib 不可用时的备用配置
├── config/ # 类型配置属性和 MCP 连接
│ ├── TdLibProperties.kt # TDLib 配置（api，auth，database，session，proxy）
│ ├── McpSecurityProperties.kt
│ ├── ServerModeProperties.kt
│ └── McpConfig.kt # 工具注册，配置文件，账户选择器
├── controller/ # 已知描述符和 OAuth 元数据端点
├── model/ # 领域模型
│ ├── TelegramModels.kt
│ ├── EntityIdentifier.kt # 密封层次结构：NumericId / Username / PhoneNumber
│ └── UserInfo.kt # UserInfo + ContactInfo
├── security/ # Spring Security，API 密钥，账户范围
│ ├── SecurityConfig.kt
│ ├── ApiKeyAuthFilter.kt
│ ├── AccountAccessPolicy.kt
│ └── SecretResolver.kt # *_FILE 挂载的机密验证
├── service/ # 业务逻辑
│ ├── EntityResolverService.kt # @username / +phone / ID 解析
│ ├── GuardrailService.kt # 输入限制和聊天访问
│ ├── OperationGuardService.kt # 只读和确认模式
│ ├── ToolSurfacePolicy.kt # 工具配置文件和允许/拒绝过滤器
│ ├── AntiSpamGuardService.kt # 速率限制，每日上限，重复数据删除
│ ├── AuditService.kt # 审计日志
│ └── FileSecurityService.kt # 文件上传安全
├── tool/ # MCP 工具（自动发现）
│ ├── McpToolHandler.kt # 工具接口
│ ├── message/ # 29 消息工具
│ ├── chat/ # 49 聊天，文件夹，权限和隐私工具
│ ├── user/ # 16 用户/联系人工具
│ ├── media/ # 7 媒体工具
│ ├── draft/ # 3 草稿工具
│ ├── research/ # 3 有界公共搜索工具
│ └── meta/ # 3 清单/账户工具
├── util/ # StructuredLogger，TextFormatter，MdcFilter
└── exception/ # McpExceptions，GlobalExceptionHandler
```
## 测试
```bash
# 单元测试
./gradlew test
# 特定测试类
./gradlew test --tests "dev.telegrammcp.server.service.GuardrailServiceTest"
```
## 贡献和支持
在打开拉取请求之前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，
在 [CHANGELOG.md](CHANGELOG.md) 中查看发布历史。
对于漏洞，请不要公开问题；
请遵循 [SECURITY.md](SECURITY.md)。
社区标准参见 [CODE_OF_CONDUCT.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](LICENSE)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器