Telegram MCP

Name: Telegram MCP
Author: n24q02m

本地服务

github.com/n24q02m通信协作111 天前更新

代码仓库

关于 Telegram MCP

Telegram MCP 为 AI Agent 提供 Telegram 消息、聊天、媒体和联系人的操作能力，支持 Bot API 与用户账号两种模式。它包含 6 个工具组，可通过 stdio 或带认证的 HTTP 提供服务，并提供文档资源。

主要功能

01支持 Bot API 和 MTProto 用户账号模式
02管理消息、聊天、媒体和联系人
03通过 stdio 或 HTTP 提供 MCP
04支持多用户令牌与独立命名空间
05提供 Telegram 文档 MCP 资源
06防 SSRF、路径遍历并标记不可信内容

适用场景

01发送、搜索或管理 Telegram 消息
02管理群组、频道和论坛主题
03发送或下载媒体文件
04通过用户账号管理联系人

MCP 相关

该 MCP 服务向客户端提供消息、聊天、媒体、联系人、配置和帮助工具，并公开 Telegram 文档资源。支持 stdio 和 HTTP 传输。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "n24q02m-better-telegram": {
      "command": "uvx",
      "args": [
        "n24q02m-telegram"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "<TELEGRAM_BOT_TOKEN>",
        "TELEGRAM_API_ID": "<TELEGRAM_API_ID>",
        "TELEGRAM_API_HASH": "<TELEGRAM_API_HASH>"
      }
    }
  }
}

启动命令uvx n24q02m-telegram

需要配置的环境变量

TELEGRAM_BOT_TOKEN密钥Telegram bot token from @BotFather (for bot mode)

TELEGRAM_API_IDTelegram API ID from my.telegram.org (for user mode)

TELEGRAM_API_HASH密钥Telegram API hash from my.telegram.org (for user mode)

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypin24q02m-telegram4.23.0stdio

ocidocker.io/n24q02m/telegram:lateststdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

mcp-name: io.github.n24q02m/better-telegram-mcp

面向 AI Agent 的 Telegram：支持机器人和用户账户模式下的消息、聊天、媒体和联系人。

n24q02m 的姊妹项目（点击展开）

| 项目 | 标语 | 标签 | |---|---|---| | [agent-chat-plugin](https://github.com/n24q02m/agent-chat-plugin) | AI Agent 在共享文件夹中点对点聊天——无需人工中转，无需协调器，wor... | 工具 | | [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | 用于提高令牌效率的代码审查知识图谱——语义搜索和调用-... | MCP | | [better-drive](https://github.com/n24q02m/better-drive) | 双向 Google Drive 同步，支持 .driveignore 过滤器——rclone 引擎，Windows 系统托盘 | 工具 | | [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | 为 AI Agent 提供 IMAP/SMTP 电子邮件功能——读取、发送、整理文件夹并管理 att... | MCP | | [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | 面向 Godot Engine 的组合式 MCP 服务——提供 17 个组合工具，支持 AI 辅助开发... | MCP | | [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | 面向 AI Agent 的 Markdown 优先 Notion——页面、数据库、内容块和评论... | MCP | | [better-semantic-release](https://github.com/n24q02m/better-semantic-release) | 可直接替换 python-semantic-release 的分支，内置发布安全防护（orp...） | 工具 | | [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | 为 AI Agent 提供 Telegram 功能——跨两个 Bo...管理消息、聊天、媒体和联系人 | MCP | | [better-workspace-mcp](https://github.com/n24q02m/better-workspace-mcp) | Google Workspace MCP 服务（Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...） | MCP | | [claude-plugins](https://github.com/n24q02m/claude-plugins) | 面向 n24q02m MCP 服务的 Claude Code 插件市场——安装网页搜索... | 市场 | | [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | 为 AI Agent 提供图像和视频理解与生成能力——支持 Gemini、Op... | MCP | | [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | Chrome 扩展，可通过 batchexecute API 批量操作 Jules 任务——a... | 工具 | | [mcp-core](https://github.com/n24q02m/mcp-core) | 用于构建 MCP 服务的共享基础组件——Streamable HTTP 传输、OAuth... | MCP | | [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | 具备混合搜索和嵌入式同步功能的持久化 AI 记忆。开放、免费、无限... | MCP | | [qwen3-embed](https://github.com/n24q02m/qwen3-embed) | 通过 ONNX Runtime 和 GGUF 实现轻量级 Qwen3 文本嵌入与重排序 | 库 | | [skret](https://github.com/n24q02m/skret) | 无需服务端的密钥管理。 | 命令行工具 | | [tacet](https://github.com/n24q02m/tacet) | 一种自蒸馏神经符号级联，可将大模型成本分摊到知识... | 工具 | | [web-core](https://github.com/n24q02m/web-core) | 用于搜索、抓取、HTTP 安全和 st...的共享 Web 基础设施包 | 库 | | [wet-mcp](https://github.com/n24q02m/wet-mcp) | 面向 AI Agent 的开源 MCP 服务：网页搜索、内容提取和 lib... | MCP |

双模式 -- Bot 使用 Bot API（httpx），用户账号使用 MTProto（Telethon）
6 个工具，支持操作分发：message、chat、media、contact、config、help
自动检测模式 -- 设置 bot token 即可使用 bot 模式，设置电话号码即可使用用户模式
本地 CLI 身份验证 -- telegram auth 在运行服务的机器上处理 bot token，或电话号码 + OTP + 2FA
Stdio 或 HTTP -- 默认使用 stdio；HTTP 支持无身份验证（仅限 loopback）、单个 bearer token 或按用户设置的 token
工具注释 -- 每个工具都会声明 readOnlyHint、destructiveHint、idempotentHint、openWorldHint
MCP 资源 -- 文档以 telegram://docs/* 资源的形式提供
强化安全性 -- SSRF 防护、路径遍历防护、错误信息清理，以及 Telegram 内容的提示注入边界标记

安装

# Claude Code plugin (stdio, bot mode)
/plugin marketplace add n24q02m/claude-plugins
/plugin install better-telegram-mcp@n24q02m-plugins

# Direct uvx invocation (stdio, bot mode)
claude mcp add telegram -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF -- uvx n24q02m-telegram

# Docker stdio
docker run -i --rm -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF n24q02m/telegram

软件包名为 n24q02m-telegram（原名 better-telegram-mcp；旧软件包将在发布最后一个版本后停止更新）。MCP Registry ID 仍为 io.github.n24q02m/better-telegram-mcp，Docker 镜像为 n24q02m/telegram，旧命令 better-telegram-mcp 仍作为 telegram 的别名保留。本地数据首次启动时会从 ~/.better-telegram-mcp 一次性迁移到 ~/.telegram。

安装矩阵

客户端	安装
Claude Code	`/plugin marketplace add n24q02m/claude-plugins` + `/plugin install better-telegram-mcp@n24q02m-plugins`（stdio bot 模式），或使用上方代码块中的 `claude mcp add`
Cursor / Windsurf / Gemini CLI / 任意 MCP 客户端	在客户端配置中设置 `mcpServers` JSON：stdio 使用 `command`，或使用 `type: "http"` + `url` 指向你运行的服务（参见 HTTP 模式）

使用 AI Agent 安装 -- 将以下内容粘贴给你的 AI 编码 Agent：

按照以下步骤安装 MCP 服务 telegram： https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-telegram-mcp/setup-with-agent.md

设置

凭据需在运行服务的机器上配置。

Bot 模式： 在客户端配置中设置 TELEGRAM_BOT_TOKEN，或保存一次：

telegram auth --bot-token 123456:ABC-DEF

用户模式： 使用电话号码交互式登录。Telegram 会发送 OTP；如果账号启用了 2FA，系统会提示输入 2FA 密码。Telethon 会话会保存在磁盘上。

telegram auth --phone +15551234567

使用 telegram status 检查结果。服务会在启动时读取已保存的凭据，因此运行 telegram auth 后需要重启服务。如果没有任何凭据，stdio 服务会将这些说明输出到 stderr 并以状态码 1 退出。

Smithery

也可在 Smithery 上找到。根据 smithery.yaml，Smithery 使用 uvx --python 3.13 n24q02m-telegram 通过 stdio 启动服务，且安装时无需配置（configSchema 为空）。凭据来自 TELEGRAM_BOT_TOKEN 环境变量或之前运行的 telegram auth（参见设置）。

配置

设置从带 TELEGRAM_ 前缀的环境变量加载（Pydantic Settings）。环境变量的优先级高于通过 telegram auth 保存的凭据。

变量	必需	描述
`TELEGRAM_BOT_TOKEN`	Bot 模式	来自 @BotFather 的 bot token（格式为 `123456789:ABCdef...`）
`TELEGRAM_PHONE`	用户模式	格式为 `+<country><number>` 的电话号码
`TELEGRAM_API_ID` / `TELEGRAM_API_HASH`	否	覆盖内置的公共 API 配对
`USE_BUNDLED_TELEGRAM_CLIENT`	否	设置为 `false`，要求提供自己的 API 配对
`TELEGRAM_SESSION_NAME`	否	Telethon 会话文件名（默认值为 `default`）
`TELEGRAM_DATA_DIR`	否	会话目录（默认值为 `~/.telegram`）
`MCP_TRANSPORT`	否	设置为 `http`，以 HTTP 模式启动（也可使用 `--http` 或 `TRANSPORT_MODE=http`）

没有 TELEGRAM_PASSWORD 环境变量：telegram auth 会提示输入 2FA 密码，且绝不会将其存储在环境变量中。

HTTP 模式

telegram --http 在 /mcp 提供 MCP 服务，并提供一个无需身份验证的 GET /health。设置位于 ~/.telegram/config.toml：

[server]
host = "127.0.0.1"   # default; --host overrides
port = 8000          # default; --port overrides
auth = "token"       # "no-auth" | "token" | "multi"
token_hash = "scrypt$..."

`auth`	可连接的对象	使用的凭据
`no-auth`	任何能够访问该端口的对象；仅绑定到环回地址（若指定非环回主机，则会被拒绝）	默认凭据
`token`	发送 `Authorization: Bearer <token>` 且与 `token_hash` 匹配的客户端	默认凭据
`multi`	`users.toml` 中列出的用户（默认路径为 `~/.telegram/users.toml`），每位用户都有自己的令牌	每位用户各自的命名空间

使用 telegram token hash 创建令牌哈希（它会从标准输入或提示中读取令牌，绝不会从命令行读取）。在 multi 模式下，通过编辑 users.toml 并重启服务来添加用户：

[users.alice]
token_hash = "scrypt$..."
enabled = true
namespace = "alice"

然后在服务所在的机器上为该用户授权 Telegram：

telegram auth --phone +15551234567 --user alice

若要访问另一台机器上的服务，请将其置于终止 TLS 的反向代理或专用网络之后，并使用 token 或 multi 身份验证。

命令行界面

telegram 控制台脚本（通过 uvx / pip 安装；better-telegram-mcp 是旧版别名）在不带子命令运行时会启动 MCP 服务。非子命令标志会传递给服务（例如 --http、--host、--port）。

telegram            # start the MCP server (stdio)
telegram --http     # start in HTTP mode
telegram --version  # print the version

子命令	用法	说明
`auth`	`auth --bot-token <token>` 或 `auth --phone <+number>`，可选 `--user <ns>`	为此机器授权。机器人模式会验证令牌；手机模式会运行交互式 OTP/2FA 流程，并将 Telethon 会话保存在磁盘上
`login`	与 `auth` 使用相同的参数	`auth` 的弃用别名
`logout`	`logout [--yes] [--user <ns>]`	撤销 Telegram 会话，删除会话文件和已保存的凭据
`config`	`config status`、`config delete --yes`	显示或删除已保存的凭据配置
`status`	`status`	显示是否已配置凭据
`doctor`	`doctor`	输出环境诊断信息
`token`	`token hash`	为 `config.toml` / `users.toml` 中的 Bearer 令牌生成哈希

--user 用于选择存储命名空间（默认值为 default，stdio 和 no-auth / token HTTP 模式使用此命名空间）。未知子命令会以状态码 2 退出。

工具

工具	操作	说明
`message`	`send`、`edit`、`delete`、`forward`、`pin`、`react`、`search`、`history`	发送、编辑、删除和转发消息。置顶、添加回应、搜索和浏览历史记录
`chat`	`list`、`info`、`create`、`join`、`leave`、`members`、`admin`、`settings`、`topics`	列出和管理聊天、群组及频道。管理成员、管理员和论坛话题
`media`	`send_photo`、`send_file`、`send_voice`、`send_video`、`download`	发送照片、文件、语音消息和视频。从消息中下载媒体
`contact`	`list`、`search`、`add`、`block`	列出、搜索和添加联系人。屏蔽/取消屏蔽用户（仅用户模式）
`config`	`status`、`set`、`cache_clear`	服务状态、运行时设置（`message_limit`、`timeout`）、缓存
`help`	--	任意主题的完整文档

MCP 资源

URI	内容
`telegram://docs/messages`	消息操作参考
`telegram://docs/chats`	聊天管理参考
`telegram://docs/media`	媒体发送/下载参考
`telegram://docs/contacts`	联系人管理参考
`telegram://stats`	所有文档的汇总

对比

在各项能力上，telegram 与直接竞品的对比：

能力	telegram	chigwell/telegram-mcp	sparfenyuk/mcp-telegram	guangxiangdebizi/telegram-mcp
Bot API 模式（Bot token）	是（httpx）	否	否	是
MTProto 用户账户模式	是（Telethon）	是	是	否
发送／编辑／删除消息	是	是	否（只读，仅草稿）	是（仅发送）
从消息下载媒体	是	是	是	否（仅发送）
联系人管理（添加／屏蔽）	是（用户模式）	是	部分支持（仅列表）	否
多用户 HTTP，按用户隔离	是（按用户划分令牌和命名空间）	否	否	否
SSRF 防护	是（URL 验证 + DNS 重绑定防护）	？	？	否
路径遍历防护	是	是（校验真实路径是否位于允许的根目录中）	？	否
可自托管	是	是	是	是

安全性

SSRF 防护 —— 验证所有 URL，确保其不指向内部／私有 IP 地址，并阻止 DNS 重绑定
路径遍历防护 —— 验证文件路径，阻止访问敏感目录
会话文件安全 —— 权限为 600；以提示方式输入双重验证密码，绝不会将其存储在环境变量中
错误信息清理 —— 错误消息和日志中绝不会泄露凭据和 Bot token
提示词注入边界 —— 工具返回的 Telegram 内容会被包裹在不可信内容标签中

从源代码构建

git clone https://github.com/n24q02m/telegram.git
cd telegram
uv sync
uv run telegram

信任模型

本项目不运营托管的 Telegram 端点。服务运行在由你控制的基础设施上，凭据绝不会离开该机器。

数据	位置	保护方式
已保存的凭据（Bot token／电话号码）	`~/.telegram/config.json`；`multi` 模式下为 `~/.telegram/subs/<ns>/config.json`	使用机器密钥 `~/.telegram/.secret` 进行 AES-256-GCM 加密
Telethon 会话	`~/.telegram/<name>.session`；`multi` 模式下为 `~/.telegram/subs/<ns>/`	文件权限 0600
HTTP bearer token	`config.toml` / `users.toml` 中的 `token_hash`	仅以 scrypt 哈希形式存储

任何能够访问你的操作系统用户账户的人都可以读取这些文件。

许可证

Apache-2.0 —— 参见 LICENSE。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

Telegram MCP

关于 Telegram MCP

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

telegram

目录

安装

安装矩阵

设置

Smithery

配置

HTTP 模式

命令行界面

工具

MCP 资源

对比

安全性

从源代码构建

信任模型

许可证

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？