fast-mcp-telegram

Telegram MCP Server — Telegram 的 Model Context Protocol (MCP) 网关。提供 8 个节省上下文的工具，支持多租户和 MTProto 桥接。

GitHub 上的规范仓库：alexeyleshchenko/fast-mcp-telegram。这是此前以 leshchenko1979/fast-mcp-telegram 名义发布的同一项目。旧版 GitHub URL 返回公开的 404 页面。安装方式仍为 pip install fast-mcp-telegram 或 uvx --from fast-mcp-telegram；PyPI 是稳定的入口。

试用演示

1. 打开 https://tg-mcp.l1979.ru/setup
2. 使用 Telegram 手机客户端扫描二维码（设置 → 设备 → 扫描二维码）——无需输入手机号、无需 OTP，也无需 2FA。也可输入手机号作为备用方式。
3. 从成功页面复制 Bearer 令牌

然后选择使用方式：

MCP 客户端（AI 助手）

• 从设置页面下载 mcp.json 文件
• 将服务添加到 AI 客户端，然后询问：“向 Telegram 中我的已保存消息发送 hello”

直接调用 API（curl）

• 运行下方命令（将 TOKEN 替换为你的令牌）：

curl -X POST "https://tg-mcp.l1979.ru/mtproto-api/messages.SendMessage" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"params": {"peer": "me", "message": "Hello!"}}'

工作原理

此服务位于你的 AI Agent 与 Telegram API 之间：

Your agent → MCP/HTTP → this server → MTProto → Telegram

**功能：**通过 Telegram 进行身份验证（二维码、手机号或机器人令牌），提供 8 个适用于 AI 的工具，取代 80 多个微型 API，并为高级用户桥接原始 MTProto。支持多租户——一个服务供多位用户使用，且会话彼此隔离。

功能

功能	描述
:building_construction: 双传输方式	为本地 MCP 客户端提供 Stdio，为远程部署提供 HTTP（生产环境使用 http-auth，开发环境可选 http-no-auth）
:closed_lock_with_key: 多用户身份验证	共享的 http-auth 服务：每位用户一个 Bearer 令牌，每个 MCP 连接对应一个 Telegram 账号。通过 QR 登录 即时完成身份验证，无需手机号、OTP 或 2FA。
:dart: 针对 AI 优化	将 80 多个微型工具整合为 8 个工具——设计注重上下文效率，提供适合大模型的 API 和 MCP ToolAnnotations
:globe_with_meridians: HTTP-MTProto 桥接	通过 curl 直接访问任意 Telegram API 方法，并提供实体解析和安全防护
:shield: 会话 ACL	可选的 http-auth 主体级限制（ACL_ENABLED）——聊天通道、read_only、blocked_peers、allow_mtproto、ACL_DENY_UNLISTED_PRINCIPALS；详见 SECURITY.md
:tv: QR 码与网页设置	使用 Telegram 手机端扫描 QR 码即可即时完成身份验证（无需手机号、OTP 或 2FA），也可使用手机号／验证码／2FA 作为备用方式——访问 /setup
:label: 一个 Agent，多个账号	可选的 PREFIX_MCP_TOOLS_WITH_ACCOUNT——当一个 Agent 使用多个 MCP 连接（同一服务，不同令牌）时，为工具名称添加前缀以避免冲突；标准多用户托管无需此设置
:rocket: MTProto 代理支持	通过 MTProto 代理连接，支持自动 Fake TLS（EE 前缀）和标准代理检测
:card_file_box: 统一会话管理	设置和服务共用一个配置系统；在共享的多用户主机上按令牌存储会话文件
:cloud: S3 会话存储	将会话存储在兼容 S3 的对象存储中，适用于临时托管部署（Smithery、Fly.io、Railway）
:mag_right: 智能搜索	支持全局和单个聊天中的消息搜索，支持多查询和智能去重
:mag: 统一消息 API	使用单个 get_messages 工具进行搜索、浏览、按 ID 读取和查看回复——一个工具包含 5 种模式
:speech_balloon: 通用回复	通过一个参数获取频道帖子、论坛主题或任意消息的回复
:busts_in_silhouette: 智能联系人发现	搜索用户、群组和频道，采用统一的实体架构，支持论坛检测和资料补全
:file_folder: 文件夹筛选	按对话文件夹（归档文件夹、自定义文件夹）筛选聊天，可通过整数 ID 或名称匹配
:envelope: 高级消息功能	发送、编辑和回复消息，发布到论坛主题，支持格式设置、文件附件和手机号消息
:paperclip: 安全文件处理	支持丰富的媒体共享，并提供 SSRF 防护、大小限制、相册支持和可选的 HTTP 附件流式传输
:outbox_tray: 内联文件上传	在 files 参数中通过 Data URI（base64）上传文件——适用于所有传输模式，保留文件名，图片以照片形式发送
:microphone: 语音转录	为 Premium 账号自动进行语音转文本，支持并行处理和轮询
:zap: 高性能	异步操作、并行查询和注重内存效率的批处理
:shield: 生产环境可靠性	自动重新连接、可配置日志记录和全面的错误处理

快速开始

1. 安装并进行身份验证

最快方式（远程服务）： 打开 /setup → 扫描二维码 → 复制令牌（参见试用演示）。

CLI 方式（本地 stdio）： 运行一次 fast-mcp-telegram-setup，创建 Telegram 会话，然后由 fast-mcp-telegram 提供服务：

uvx --from fast-mcp-telegram fast-mcp-telegram-setup \
  --api-id="your_api_id" \
  --api-hash="your_api_hash" \
  --phone-number="+123456789"

Bot 令牌替代方式（无需手机号，无需 OTP）： 设置 BOT_API_TOKEN，而不是使用 --phone-number。参见安装指南。

2. 配置 MCP 客户端

stdio 模式（本地）： 将其添加到 MCP 客户端配置中（例如 claude_desktop_config.json）——stdio（标准输入/输出）是本地 MCP 客户端的默认传输方式：

{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": ["fast-mcp-telegram"],
      "env": {
        "API_ID": "your_api_id",
        "API_HASH": "your_api_hash"
      }
    }
  }
}

http-auth 模式（远程）： 将其添加到 MCP 客户端配置中（例如 claude_desktop_config.json）：

{
  "mcpServers": {
    "telegram": {
      "url": "https://tg-mcp.l1979.ru/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

扫描设置页面上的二维码获取令牌，或参见安装指南了解如何部署自己的服务。

3. 开始使用

{"tool": "search_messages_globally", "params": {"query": "hello", "limit": 5}}
{"tool": "get_messages", "params": {"chat_id": "me", "limit": 10}}
{"tool": "send_message", "params": {"chat_id": "me", "message": "Hello!"}}

部署到远程服务

在 VDS 上部署自己的 MCP 服务——参见安装指南了解分步说明。

可用工具

工具	用途	主要功能
search_messages_globally	搜索所有聊天	多关键词查询、日期筛选、聊天类型筛选
get_messages	统一获取消息	搜索/浏览、按 ID 读取、获取回复（帖子/话题/消息）、所有模式均支持日期筛选
send_message	发送新消息	文件附件（URL/本地文件/数据 URI）、经典格式（markdown/html）、parse_mode=rich 富消息、回复论坛话题
edit_message	编辑现有消息	经典格式或 parse_mode=rich 格式
find_chats	查找用户/群组/频道	多关键词搜索、发现联系人、文件夹筛选、用户名/手机号查找
get_chat_info	获取详细资料信息	成员数量、简介/关于信息、在线状态、论坛话题、共同群组、增强数据
send_message_to_phone	向手机号发送消息	自动管理联系人、可选清理、支持文件（URL/数据 URI）、parse_mode=rich
invoke_mtproto	直接调用 Telegram API（高级用户）	原始 MTProto 方法、实体解析、安全防护——参见 MTProto Bridge

详细文档和示例请参见工具参考。

文档

• 安装指南 - 本地设置和远程服务部署
• 工具参考 - 完整的工具文档
• MTProto Bridge - 通过 curl 直接访问 API
• 贡献指南 - 贡献者指南
• 安全 - 安全功能和最佳实践

遥测

自 v0.30.1 起提供匿名工具遥测——每 6 小时发送一次心跳，不收集凭据或消息内容。设置 DO_NOT_TRACK=1 可选择退出。参见 ADR 0005。

自 v0.38.0 起提供身份验证流程遥测——在设置期间记录原子事件（手机号、二维码、Bot 令牌、重新授权）。流程完成后批量刷新。参见 ADR 0008。

许可证

MIT 许可证 - 参见 LICENSE

mcp-name: io.github.alexeyleshchenko/fast-mcp-telegram