mcp-telegram

Telegram 的 MCP 服务器 — 让 AI 助手与您的 Telegram 账号交互

功能

聊天管理：列出、搜索、静音/取消静音聊天
消息：读取、搜索、检查上下文、发送、草稿、定时发送、解析链接和备份消息
AI 总结：使用多种 LLM 提供商总结聊天对话
安全：会话存储在 macOS 钥匙串中（Linux/Windows 上为基于文件的存储）

安装

go install github.com/tolmachov/mcp-telegram@latest

或从源码构建：

git clone https://github.com/tolmachov/mcp-telegram.git
cd mcp-telegram
make

设置

1. 获取 Telegram API 凭据

前往 my.telegram.org/apps
创建一个应用程序
复制 api_id 和 api_hash

2. 配置环境变量

存储凭据（macOS 钥匙串；Linux/Windows 上为 ~/.local/state/mcp-telegram/config.json 中的明文 JSON，权限为 0600）：

mcp-telegram config set TELEGRAM_API_ID 123456789
mcp-telegram config set TELEGRAM_API_HASH abcd1234efgh5678

或使用 .env 文件：

cp .env.example .env
# Edit .env with your credentials

3. 登录 Telegram

mcp-telegram login --phone +1234567890

系统将提示您输入发送到 Telegram 的验证码。

4. 配置 MCP 客户端

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows)：

{
  "mcpServers": {
    "telegram": {
      "command": "mcp-telegram",
      "args": ["run"],
      "env": {
        "TELEGRAM_API_ID": "your_api_id",
        "TELEGRAM_API_HASH": "your_api_hash"
      }
    }
  }
}

Claude Code

claude mcp add telegram -- /path/to/mcp-telegram run

在您的 .env 文件中设置环境变量，或通过 --env 传递它们。

可用工具

向 MCP 客户端公开了 19 种工具。消息由不透明的字符串句柄标识（普通消息为 "42"，定时消息为 "s:42"）——请从工具输出中原样复制它们以用于后续调用，切勿手动解析或构造它们。

工具	描述
`GetMe`	获取当前用户信息
`GetChats`	列出所有聊天、群组和频道
`SearchChats`	按名称模糊搜索聊天
`GetChatInfo`	获取聊天的详细信息
`GetMessages`	从聊天中获取消息（设置 `include_scheduled=true` 可在单独字段中列出待处理的定时消息）
`SearchMessages`	在单个聊天中按子字符串搜索，支持可选的日期/发送者/媒体/主题过滤器
`SearchMessagesGlobal`	在所有聊天中按子字符串搜索，支持基于不透明游标的分页
`GetMessageContext`	按时间顺序获取特定锚点消息周围的消息
`SendMessage`	发送、回复、定时发送或草拟消息。`mode` = `send`（默认）/ `schedule` / `draft`；`reply_to_message_id` 适用于任何模式；`schedule_at` 为 RFC3339 格式
`EditMessage`	编辑消息；对于定时消息句柄，`schedule_at` 可在同一次调用中重新安排发送时间
`DeleteMessage`	删除消息；`"s:<id>"` 句柄可取消待处理的定时消息
`ForwardMessage`	转发已发送的消息（定时消息句柄将被拒绝）
`ResolveMessageLink`	将 `t.me` / `tg://` 消息链接解析为 `chat_id`、`message_id`，以及论坛链接的 `topic_message_id`
`MarkAsRead`	将一个或多个聊天标记为已读
`BackupMessages`	将消息导出到文本文件（幂等；会覆盖目标文件）
`ResolveUsername`	将 @username 解析为用户/聊天信息
`SetChatMute`	静音或取消静音聊天通知（`muted` 布尔值 + 可选的 `duration_seconds`）
`SummarizeChat`	通过采样 / Gemini / Ollama / Anthropic 进行 AI 驱动的聊天总结
`GetMedia`	从消息资源 URI 下载照片媒体；返回 MCP 图像内容

可用资源

URI	描述
`telegram://me`	当前用户信息
`telegram://chats`	所有聊天列表
`telegram://chat/{id}/info`	通过资源模板获取任何聊天 ID 的详细信息
`telegram://chats/{id}`	置顶聊天的最后 100 条消息（动态资源，仅适用于当前置顶的聊天）

置顶聊天资源是为每个置顶聊天动态创建并在后台刷新的；当集合发生变化时，客户端将收到 resources/list_changed 通知。

可用提示词

3 个参数化提示词，MCP 客户端将其公开为斜杠命令或快速操作。

提示词	参数	描述
`daily-digest`	`period` — `day`（默认）/ `week` / `month`	遍历活跃聊天并生成每个聊天的关键更新和待办事项摘要。只读。
`chat-catchup`	`chat`（必填） — ID / @username / 标题；`period` — `day` / `week`（默认） / `month`	总结特定聊天并列出看起来需要回复的消息。只读。
`find-and-reply`	`chat`（必填），`query`（必填） — 要搜索的内容，`reply`（必填） — 回复文本或指令	搜索消息，显示回复草稿，并仅在用户明确确认后发送。

提示词示例

以下是您可以与 AI 助手一起使用的一些示例提示词：

消息管理

“检查我的 Telegram 中是否有未读的重要消息”
“总结我所有未读的 Telegram 消息”
“阅读并分析我的未读消息，在需要时准备回复草稿”
“检查非紧急的未读消息并给我一个简要概述”
“查找上周工作聊天中提到 'invoice' 的消息”
“打开此 Telegram 链接周围的上下文：https://t.me/example/123”

组织

“分析我的 Telegram 对话并建议一个文件夹结构”
“帮我按重要性对我的 Telegram 聊天进行分类”
“查找所有与工作相关的对话并建议如何组织它们”

通信

“监控特定聊天以获取关于 [topic] 的更新”
“为 [chat] 中的最后一条消息起草一份礼貌的回复”
“检查我的聊天中是否有任何未回答的问题”
“解析此 Telegram 消息链接并向我展示主题上下文”

备份与导出

“将我与 [contact] 的对话备份到文件”
“导出 [group] 中过去一周的消息”
“同时备份仅包含媒体的更新，以免遗漏任何内容”

聊天总结

SummarizeChat 工具支持多种 LLM 提供商：

sampling（实验性）：通过 MCP Sampling 使用 MCP 客户端的 LLM。仅适用于支持采样的客户端：VS Code、fast-agent、Continue。不适用于 Claude Desktop 或 Claude Code。
ollama：通过 Ollama 使用本地 LLM - 无需 API 密钥
gemini：Google Gemini API
anthropic：Anthropic Claude API

通过环境变量进行配置：

SUMMARIZE_PROVIDER=ollama  # or: sampling, gemini, anthropic
SUMMARIZE_MODEL=           # provider-specific model name

命令

# Run MCP server (used by MCP clients)
mcp-telegram run

# Login to Telegram
mcp-telegram login --phone +1234567890

# Logout and delete session
mcp-telegram logout

# Securely store config values (macOS Keychain / file on Linux)
mcp-telegram config set TELEGRAM_API_ID 123456789
mcp-telegram config set TELEGRAM_API_HASH abcd1234

# List stored keys
mcp-telegram config list

# Delete a stored value
mcp-telegram config delete TELEGRAM_API_ID

允许的键：TELEGRAM_API_ID, TELEGRAM_API_HASH, ANTHROPIC_API_KEY, GEMINI_API_KEY。

配置选项

环境变量	描述	默认值
`TELEGRAM_API_ID`	Telegram API ID	必填
`TELEGRAM_API_HASH`	Telegram API Hash	必填
`TELEGRAM_ALLOWED_PATHS`	允许备份的目录	OS 应用数据目录
`SUMMARIZE_PROVIDER`	总结的 LLM 提供商	`sampling`（实验性）
`SUMMARIZE_MODEL`	模型名称	提供商默认值
`SUMMARIZE_BATCH_TOKENS`	每个总结批次的 Token 数	`8000`
`OLLAMA_URL`	Ollama API URL	`http://localhost:11434`
`GEMINI_API_KEY`	Google Gemini API 密钥	-
`ANTHROPIC_API_KEY`	Anthropic API 密钥	-
`TELEGRAM_MEDIA_MAX_BYTES`	`GetMedia` 每次调用下载的最大字节数（上限以避免大附件导致内存溢出）	`52428800` (50 MiB)
`TELEGRAM_RATE_LIMIT_RPS`	获取 Telegram 历史记录调用的 RPS 上限。超过 Telegram 的 FLOOD_WAIT 阈值将暂停所有工具。	`0`（安全的内置默认值）
`TELEGRAM_PINNED_REFRESH_SECONDS`	置顶聊天资源监视器的轮询间隔（秒）。`0` 禁用监视器。	`30`

破坏性操作

像 DeleteMessage 这样的工具在执行前会通过 MCP elicitation 请求用户确认。如果您的 MCP 客户端不支持 elicitation，服务器将依赖 LLM 的指令在执行破坏性操作前进行口头确认。

会话存储

macOS：安全存储在钥匙串中。
Linux/Windows：存储在 ~/.local/state/mcp-telegram/session.json 中，文件权限为 0600。该文件是明文的 — 请确保包含该文件的用户账号是受信任的，在处理敏感账号时优先在 macOS 上运行。

通过 mcp-telegram config set 设置的配置值（API 密钥、Telegram 凭据）遵循相同的后端：macOS 上为钥匙串，Linux/Windows 上为明文 JSON。

许可证

MIT

MCP Telegram