chigwell/telegram-mcp

Telegram MCP server powered by Telethon to let MCP clients read chats, manage groups, and send/modify messages, media, contacts, and settings.

Telegram MCP Server – 它是什么

Telegram MCP 是一个自托管的 Python 服务器，让 AI 代理（Claude、Cursor 或任何支持 模型上下文协议（MCP）的客户端）能够像使用一组原生工具一样与 Telegram 账户交互。它将 MCP 工具调用转换为基于 Telethon 的 Telegram API 操作，暴露你在 Telegram 中能做的所有事情——阅读聊天、发送消息、管理群组、处理联系人、媒体、文件夹、事件，甚至语音转文本转录。

核心概念

MCP ↔ Telegram 桥接 – 服务器实现了开源的模型上下文协议，将 Telegram 操作转化为结构化的基于 JSON 的工具，供 LLM 驱动的代理调用。
代理友好 – 结果经过清理的 JSON，服务器报告特殊错误对象（例如 telegram_premium_required），以便代理调整其行为。

你可以用它做什么

领域	示例能力
账户	列出多个配置的账户，按标签路由调用。
聊天与群组	列出聊天，创建/加入/离开群组，管理管理员、封禁、慢速模式、话题、邀请链接、已读回执等。
消息	发送、编辑、删除、转发、定时、置顶、回应、创建投票、回复、搜索、获取上下文，并使用富格式（Markdown/HTML，支持表格、公式、可折叠部分）——仅限高级版。
联系人	列出、搜索、添加、屏蔽、导入/导出，并记住别名（例如，教授别名后 `send_message("андрей бекендер", …)` 即可工作）。
媒体	上传/下载文件、贴纸、GIF、语音消息，并使用四种引擎之一转录语音/视频（Groq Whisper、Telegram Premium、OpenAI 兼容或本地 Faster-Whisper）。
个人资料与隐私	获取/设置个人资料信息、照片、隐私设置、机器人命令。
文件夹与草稿	列出、创建、重新排序、删除文件夹；保存、列出、清除草稿；快照文件夹定义以备份/恢复。
事件	等待新消息（`wait_for_new_message`），或启用回调式传入馈送，将 JSON 行写入文件，供可以监控文件的代理使用（例如 Claude Code）。
自定义表情符号与可点击日期	检索自定义表情符号 ID，并通过 `<tg-emoji>` 标签重用；使用 `format_date` 嵌入可点击的日期芯片。

语音转录详情

Groq – 托管的 Whisper-large-v3-turbo，需要 GROQ_API_KEY。默认上传上限为 25 MiB。
Telegram – 使用 Telegram Premium 的原生转录（免费，留在 Telegram 上），但可能丢失最后一段。
OpenAI – 任何 /audio/transcriptions 端点（OpenAI、Parakeet、LocalAI 等）。
Whisper – 本地 Faster-Whisper 模型（pip install 'telegram-mcp[whisper]'）。

转录结果缓存在 SQLite 文件中；重复请求命中缓存，并发相同请求合并。

快速开始

克隆并安装 – git clone https://github.com/chigwell/telegram-mcp.git && uv sync（需要 Python 3.10+）。
创建会话字符串 – uv run session_string_generator.py（二维码或电话号码流程）。
配置 – 将 .env.example 复制为 .env，并填写 TELEGRAM_API_ID、TELEGRAM_API_HASH 和 TELEGRAM_SESSION_STRING。
运行 – uv run telegram-mcp（或通过 Docker – 见下文）。
可选 – 迁移到持久化 SQLite 会话（uv run telegram-mcp-migrate-session）以用于长时间运行的服务器。

部署选项

Docker – 官方镜像自动构建；挂载卷用于 data/transcripts（转录缓存）和状态目录（~/.local/state/telegram-mcp）。
多账户 – 在 .env 中定义多个账户（例如 ACCOUNT_1_LABEL、ACCOUNT_2_LABEL），并通过 account 参数路由调用。
代理支持 – 将 TELEGRAM_PROXY 设置为 SOCKS/HTTP 代理 URL。
安全 – 存储别名、会话数据和传入馈送日志的文件以仅所有者权限（600/700）创建。README 警告不要安装同名的 PyPI 包 telegram-mcp，因为它无关。

谁可能使用这个？

LLM 驱动的个人助理，需要读取或操作 Telegram 消息（例如 Claude Code、Cursor、自定义 MCP 主机）。
自动化工程师，构建跨多个 Telegram 账户操作的机器人，同时将逻辑保留在 LLM 中，而不是硬编码脚本。
研究人员，探索 LLM 如何安全地与真实世界消息平台交互，得益于明确的错误对象和隐私导向设计（允许列表聊天访问、别名确认等）。

许可证与社区

许可证： Apache 2.0 – 允许商业和研究使用。
状态： 积极维护（GitHub Actions 用于 linting、Docker 构建和 CI）。欢迎通过拉取请求贡献。

TL;DR

Telegram MCP Server 是一个 Python 桥接器，将 Telegram 转化为一组丰富的 MCP 兼容工具，使 LLM 代理能够以编程方式读取、写入、管理和转录 Telegram 内容，支持多账户、富文本格式、自定义表情符号以及安全、缓存感知的语音转录。