Telegram Archive Mcp

telegram-archive-mcp

适用于任何 Telegram-Archive 实例的 MCP 服务。大模型可用它搜索消息、浏览聊天，并阅读归档的 Telegram 历史记录。

功能

• 支持 MCP 2026-07-28 及所有更早版本，最早可追溯至 2024-11-05，可通过 stdio 和 Streamable HTTP 通信。仍使用 initialize 握手的客户端也能正常工作。
• 可搜索单个聊天或一次搜索所有聊天；分页读取聊天内容、按你的时区读取某个日历日的内容，或读取某条消息前后的对话。
• 支持论坛主题、置顶消息、文件夹和单个聊天的统计信息。
• 将消息附带的照片作为模型可查看的图像返回；如果图像大于 1568 像素，则会缩放（get_media）。
• 除 refresh_stats 外，所有工具均为只读；READ_ONLY=1 也会隐藏该工具。
• 通过 /api/login 使用 TELEGRAM_ARCHIVE_USER 和 TELEGRAM_ARCHIVE_PASS 登录 Telegram-Archive。
• HTTP 默认监听 loopback 地址，会检查 Origin、限制请求正文大小，并要求在任何其他地址上提供 MCP_AUTH_TOKEN。
• 提供 npm 包、Docker 镜像和多架构 Go 二进制文件。

安装

以下客户端均通过 stdio 运行该服务。请设置 Telegram-Archive 查看器的网址、用户名和密码。

Claude Code

claude mcp add --env TELEGRAM_ARCHIVE_URL=http://localhost:8000 \
  --env TELEGRAM_ARCHIVE_USER=admin --env TELEGRAM_ARCHIVE_PASS=your-viewer-password \
  --transport stdio telegram-archive -- npx -y telegram-archive-mcp

Claude Desktop（claude_desktop_config.json）和 Cursor（~/.cursor/mcp.json）

{
  "mcpServers": {
    "telegram-archive": {
      "command": "npx",
      "args": ["-y", "telegram-archive-mcp"],
      "env": {
        "TELEGRAM_ARCHIVE_URL": "http://localhost:8000",
        "TELEGRAM_ARCHIVE_USER": "admin",
        "TELEGRAM_ARCHIVE_PASS": "your-viewer-password"
      }
    }
  }
}

VS Code（.vscode/mcp.json，密码仅需输入一次）

{
  "inputs": [
    { "type": "promptString", "id": "tg-pass", "description": "Telegram-Archive viewer password", "password": true }
  ],
  "servers": {
    "telegram-archive": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "telegram-archive-mcp"],
      "env": {
        "TELEGRAM_ARCHIVE_URL": "http://localhost:8000",
        "TELEGRAM_ARCHIVE_USER": "admin",
        "TELEGRAM_ARCHIVE_PASS": "${input:tg-pass}"
      }
    }
  }
}

Codex（~/.codex/config.toml）

[mcp_servers.telegram-archive]
command = "npx"
args = ["-y", "telegram-archive-mcp"]
env = { TELEGRAM_ARCHIVE_URL = "http://localhost:8000", TELEGRAM_ARCHIVE_USER = "admin", TELEGRAM_ARCHIVE_PASS = "your-viewer-password" }

Docker，适用于上述任意客户端：将 docker 用作命令，并使用以下参数；版本标签请从发布页面选择，切勿使用 latest：

docker run -i --rm -e TELEGRAM_ARCHIVE_URL -e TELEGRAM_ARCHIVE_USER -e TELEGRAM_ARCHIVE_PASS drumsergio/telegram-archive-mcp:vX.Y.Z

npm 包会在首次启动时下载发布二进制文件，并使用随包发布的校验和进行验证，因此也适用于跳过安装脚本的 npm 12。长时间运行的 HTTP 服务（Docker Compose）和本地构建的相关说明见入门指南。

工具

工具	功能
list_chats	按最近时间倒序列出聊天；可按 search（名称）、archived 或 folder_id 筛选。每个聊天的 ref 就是其他工具所需的 chat_id。
list_folders	列出你的 Telegram 文件夹及其 ID。
search_all_chats	一次搜索所有聊天中的消息文本。
search_messages	搜索单个聊天，可选搜索单个论坛主题。
get_messages	按偏移量或键集游标从新到旧读取聊天，可选读取单个论坛主题。
get_message_context	返回一条消息及其前后消息。
get_messages_by_date	按时区返回某个日历日的所有消息。
get_pinned_messages	返回聊天中的置顶消息。
get_topics	列出论坛群组的主题；主题 ID 可用作 topic_id。
get_chat_stats	统计单个聊天的消息数、媒体数及大小。
get_media	以图片形式获取消息附带的照片，或获取文件详情。
refresh_stats	使查看器重新计算整个归档的统计数据。设置 READ_ONLY=1 时隐藏。

每个工具都会返回带有输出架构的结构化内容，以及相同内容的 JSON 文本。参数和默认值请参阅用法。

文档

完整文档请访问 geiserx.github.io/telegram-archive-mcp。

• 快速入门：npm、Docker Compose、本地构建
• 配置：环境变量和客户端配置
• 用法：4 个资源和 12 个工具、分页、逐日读取
• 开发：测试、贡献、致谢
• 相关项目：Telegram Archive、其他 MCP 服务、此项目的收录位置

许可证

GPL-3.0-or-later