Telegram Context MCP

Telegram Context MCP

通过 MCP 客户端使用你自己的账号读取 Telegram。查找获准访问的对话， 搜索并阅读原始帖子，浏览话题和回复，并查看相册、表情回应 和投票。可以将多个本地客户端连接到一个持有会话的进程，也可以独立运行 STDIO。

支持 Windows、macOS 和 Linux，要求 Python 3.12–3.15。服务使用 Telethon， 并保留原始文本、日期、链接、实体和可用元数据。它不会发送消息、加入频道 或将消息标记为已读。0.4 版新增了可选择启用的附件下载、持久化变更检查点、命名订阅， 以及 JSONL/Markdown 导出（可选择永久保存副本）。只有在请求时，订阅才会轮询，并会保留批次，直到确认。 此外，它还限制了范围预览的大小、更早返回受限搜索结果、复用对话快照并接受并发调用。升级 0.3 版前，请参阅 0.4 迁移指南。

0.5 版新增了跨聊天或文件夹的有界历史记录、确认前保存的监视批次，以及带有本地监视名称 补全功能的 watch_digest / period_digest 提示词。升级时，请重启服务和客户端代理，并刷新工具 和提示词。0.5 更新日志 介绍了新增功能和归档设置。

安装并登录

安装 uv，然后运行：

uv tool install --python 3.12 telegram-context-mcp==0.5.0
telegram-mcp --version
telegram-mcp login
telegram-mcp configure
telegram-mcp status

这些示例适用于 0.5.0 版；已发布的版本请查看 PyPI。 对于尚未发布的修订版本，请使用源码设置。 从 0.3 版升级？请阅读迁移指南， 然后重启服务并刷新客户端的工具架构。

从 my.telegram.org 获取 api_id 和 api_hash，然后 在本地登录提示中输入这些信息，以及你的电话号码、登录验证码和任何 2FA 密码。请勿将登录验证码或凭据发送给模型。

configure 可让你选择文件夹/聊天，并分别启用所有聊天访问、 明确允许的公开频道读取，或公开频道发现。按 Enter 保留当前值。默认情况下，不允许访问任何消息来源。登录后，status 应显示 authorized: true。使用 catalog 在本地查找文件夹和聊天 ID。

软件包名称为 telegram-context-mcp；可执行文件为 telegram-mcp。 你也可以运行固定版本，而无需安装持久命令：

uvx --python 3.12 --from telegram-context-mcp==0.5.0 telegram-mcp --version

该服务已列入官方 MCP 注册表，名称为 io.github.egor-fedorov/telegram-mcp。 此条目通过 uvx 启动本地 STDIO 服务；它不提供托管的 Telegram 服务。连接客户端前，请在本地完成 login 和 configure。 注册表收录从 0.5.0 版开始。有关验证，请参阅 发布流程；有关在客户端之间共享一个会话，请参阅客户端指南。

连接客户端

在终端中启动一个服务并保持运行：

telegram-mcp serve --transport http

它仅监听 http://127.0.0.1:8765/mcp。将每个 MCP 客户端配置为通过 STDIO 启动 telegram-mcp connect。这个小型代理会读取本地令牌并连接到现有服务；它不会启动服务，也不会悄悄回退到其他 Telegram 会话。关闭客户端不会影响共享服务的运行。

客户端示例 介绍了 Codex、Claude Desktop、Claude Code、Cursor 和 VS Code，包括固定版本的 uvx 命令以及 Windows 的可执行文件路径。

对于单个客户端，仍可使用独立 STDIO：将该客户端配置为启动 telegram-mcp serve。每个会话只能使用一种模式。运行本地 login、configure、catalog 或 status 前，请先停止拥有该会话的 进程；服务运行时请使用 get_status MCP 工具。

所有共享客户端都使用同一个 Telegram 账号、读取权限和游标存储。HTTP bearer 令牌会在本地用户配置文件中创建，并由 connect 读取；请勿将其粘贴到客户端配置中。这是一个本地单用户集成。

工具

工具	用途
get_status	授权状态、连接状态、允许访问的来源
list_folders	文件夹、ID、顺序、包含／排除规则
list_chats	按名称、类型或文件夹筛选聊天
get_chat	描述和关联的讨论群组
search_public_channels	按查询条件查找公开广播频道；仅获取元数据
get_similar_channels	为指定的公开来源查找相似的公开频道；仅获取元数据
search_messages	按关键词、聊天、文件夹、日期、发送者、媒体类型或链接搜索
get_history	按时间范围获取聊天或论坛主题的历史记录，支持正序或倒序；聊天／文件夹时间范围有上限
list_topics	获取带导航引用的论坛主题；支持按标题查询和分页
get_pinned_messages	获取聊天或论坛主题中的置顶消息，按时间从新到旧排列
get_messages	按链接／ID 获取消息，包括作者、日期、附件、计数、反应和投票
get_album	获取指定消息有限邻近范围内所选相册的成员
get_context	获取锚点前后的消息以及一串父级回复
get_thread	获取频道帖子下的评论或群组话题中的回复
download_attachment	将一个所选附件下载为临时本地文件和 MCP 资源，大小不超过 20 MiB
get_changes	获取一个聊天中的新消息和近期观测到的修订，并提供可重启的检查点
create_watch / list_watches	保存和查找命名的聊天／文件夹订阅
get_watch_changes / ack_watch_changes	轮询并确认持久化批次，无需逐聊天令牌；也可先保存批次
delete_watch	明确丢弃订阅及其待处理批次
export_history	导出带来源链接的 JSONL 或 Markdown 历史记录，支持分段、重启且每段范围有限

两个提示词将这些工具组合起来用于监控：watch_digest 会将命名监控转换为带来源链接的摘要，并在确认每个批次前先保存； period_digest 会在明确的预算限制下读取一个聊天或文件夹在固定时间段内的内容。 它们不会增加权限。请参阅 监控提示词。

首要任务

• 请客户端列出你允许访问的文件夹，并读取指定时区日期范围内选定的对话。
• 启用发现功能以查找候选公开频道，选择来源，然后使用单独的读取权限读取其帖子。
• 使用原始筛选条件继续请求 next_cursor，直到其值为 null。空页面仍可能带有游标。临时故障后请遵守 retry_after_seconds 指定的等待时间。
• 对于 CATALOG_LOADING，请在报告的延迟后重复原始调用。服务会保留目录扫描进度；不依赖文件夹的显式读取会跳过该扫描。
• 默认情况下，搜索会在每个页面内排序。选择 ordering="global" 可按跨页面顺序排序。范围 ID 数组最多预览 20 个 ID；描述覆盖范围时，请使用其计数和截断标志。
• 使用 get_messages 和 next_text_offset 读取完整的长文本。专辑是否完整尚不明确；其中每个成员仍是单独的来源消息。

用法和响应约定 说明了筛选条件、游标恢复、话题、公开频道发现和消息元数据。 有关持久监控和选定文件，请参阅更改和导出。 消息文本是提供给调用方 Agent 的数据，不是指令来源。

配置和故障排除

配置、Telegram 会话和 HTTP 令牌均位于仓库之外的平台专属用户目录中。登录命令会显示配置路径。 使用 telegram-mcp --config /absolute/private/config.toml COMMAND 选择其他文件； 为共享服务和每个代理传入同一个文件。

在 POSIX 系统上，私有文件使用严格的权限设置。在 Windows 上，请使用用户配置文件的文件系统 ACL 保护这些文件；Unix 的 0600 并不保证 ACL 安全。Telegram 会话包含账户访问凭据，而底层账户能够执行的操作可能超出服务的 Telegram 读取权限所允许的范围。

• 配置和权限
• 故障排除
• TOML 示例
• 安全问题报告

从源代码运行

git clone https://github.com/egor-fedorov/telegram-mcp.git
cd telegram-mcp
uv sync --locked --python 3.12
uv run --locked telegram-mcp login
uv run --locked telegram-mcp configure
uv run --locked telegram-mcp serve --transport http

对于客户端命令，在 POSIX 系统上使用检出目录中的 .venv/bin/telegram-mcp，在 Windows 上使用 .venv\Scripts\telegram-mcp.exe，并将 connect 作为参数。 请使用绝对可执行文件路径，以免客户端依赖其工作目录。

开发

运行 make check，执行格式检查、lint、类型检查、架构检查和离线测试。 贡献指南 列出了无需 Make 的 Windows 等效命令。变更通过范围明确的拉取请求提交，并在 CI 通过后合并。 请参阅 路线图、 架构、 更新日志和 发布流程。 0.5 验证记录 说明了发布检查，以及所选来源和客户端验证的范围。

代码采用 MIT 许可证。 这不代表你拥有 Telegram 内容的权利。不支持秘密聊天；下载附件需要单独选择启用。要保留永久副本，需要指定归档目录并设置 save=true；发送消息、管理和持续归档仍属于未来工作。 请使用你有权与所选模型分享的来源材料，并遵循 Telegram 的内容条款。