Chatroost — unofficial Telegram MCP server

Telegram MCP 服务

📖 文档 · ☁️ 云版本 — 通过二维码在 30 秒内将 Telegram 连接到 Claude.ai 或 ChatGPT，无需 API 密钥。

Telegram MCP 服务——一个通过 MTProto 协议将 Claude 和 ChatGPT 等 AI 助手连接到 Telegram 的模型上下文协议服务。与机器人不同，它以用户机器人的形式运行——通过 GramJS 使用你的个人 Telegram 账号运行，因此可以完整访问你的聊天、联系人和消息历史记录。

功能

• 全面的工具支持——目前功能最齐全的 Telegram MCP 服务
• MTProto 协议——直接访问 Telegram API，而非受限的 Bot API
• 用户机器人——以你的个人账号运行，而不是机器人
• 功能齐全——支持消息、表情回应、投票、定时消息、贴纸、媒体、联系人等
• 论坛话题——列出话题、读取各话题的消息、向指定话题发送消息、查看各话题的未读数量
• 贴纸——搜索贴纸集、浏览已安装和最近使用的贴纸、向任意聊天发送贴纸
• 账号与个人资料管理——更新个人资料、设置表情状态、生日、个人频道和头像，管理隐私设置、会话及自动删除计时器
• 聊天文件夹——创建、编辑、删除和重新排序文件夹，切换文件夹标签，读取建议的文件夹（v1.33.0）
• 全局隐私——读取和设置账号级隐私设置（v1.33.0）
• 全局搜索——一次搜索所有聊天中的消息
• 实时轮询——通过无状态游标获取更新；由 Agent 管理 {pts, qts, date} 状态
• 内联机器人与按钮——查询内联机器人、发送结果、按下回调按钮
• 故事——读取联系人的故事、获取故事浏览统计；发布、编辑和删除故事，回应、置顶、隐身模式、归档、举报（v1.30.0）
• 讨论——获取带评论的频道帖子所对应的讨论组信息，列出符合讨论条件的群组（v1.30.0）
• 已读回执——查看小型群组中谁读过消息，以及你的私聊消息何时被读（v1.30.0）
• 管理员控制——切换频道签名、反垃圾机制、论坛模式和历史记录设置；批准加入请求
• 统计——频道和超级群组分析（GetBroadcastStats / GetMegagroupStats）
• Boost 与 Business——Boost 状态、Boost 用户列表、Telegram Business 聊天链接的增删改查、工作时间、位置、问候/离开/简介消息
• 星星礼物——浏览可用和已保存的礼物、保存/兑换礼物、管理 Stars 余额和订阅（通过 MCP_TELEGRAM_ENABLE_STARS=1 启用，v1.34.0）
• 共享守护进程——一个后台进程通过单个 Telegram 会话为多个 MCP 客户端提供服务；参阅共享守护进程指南（v1.38.0）
• 二维码登录——通过扫描 Telegram 应用中的二维码进行身份验证
• 会话持久化——登录一次，重启后仍保持连接
• 易读的输出——解析发送者姓名，而不只是显示数字 ID
• 适用于任何 MCP 客户端——Claude Code、Claude Desktop、ChatGPT、Cursor、VS Code、Mastra 等

前置条件

• Node.js 18 或更高版本
• Telegram API 凭据——从 my.telegram.org 获取 API_ID 和 API_HASH

快速开始

1. 获取 Telegram API 凭据

1. 前往 my.telegram.org，使用你的电话号码登录。
2. 前往 API development tools。
3. 创建一个新应用（名称和平台不限）。
4. 复制 App api_id 和 App api_hash。

2. 登录

TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH npx @overpod/mcp-telegram login

终端中将显示一个二维码。打开手机上的 Telegram，前往 设置 > 设备 > 关联桌面设备，然后扫描二维码。会话将保存到 ~/.mcp-telegram/session，并在之后自动复用。

**自定义会话路径：**设置 TELEGRAM_SESSION_PATH=/path/to/session，将会话文件存储到其他位置。

**两步验证（2FA）：**如果你的账号启用了云密码，仅扫描二维码还不够——Telegram 还需要密码。通过 TELEGRAM_2FA_PASSWORD 提供密码，以完成登录：

TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH TELEGRAM_2FA_PASSWORD=YOUR_PASSWORD npx @overpod/mcp-telegram login

密码仅在本地用于响应 Telegram 的 SRP 挑战，不会被持久化。

3. 添加到 Claude

claude mcp add telegram -s user \
  -e TELEGRAM_API_ID=YOUR_ID \
  -e TELEGRAM_API_HASH=YOUR_HASH \
  -- npx @overpod/mcp-telegram

完成！让 Claude 运行 telegram-status 进行验证。

多个账号

使用 TELEGRAM_SESSION_PATH 并行运行多个 Telegram 账号：

# Login each account with a unique session path
TELEGRAM_API_ID=ID1 TELEGRAM_API_HASH=HASH1 TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-work npx @overpod/mcp-telegram login
TELEGRAM_API_ID=ID2 TELEGRAM_API_HASH=HASH2 TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-personal npx @overpod/mcp-telegram login

然后将每个账号分别添加为独立的 MCP 服务：

claude mcp add telegram-work -s user \
  -e TELEGRAM_API_ID=ID1 \
  -e TELEGRAM_API_HASH=HASH1 \
  -e TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-work \
  -- npx @overpod/mcp-telegram

claude mcp add telegram-personal -s user \
  -e TELEGRAM_API_ID=ID2 \
  -e TELEGRAM_API_HASH=HASH2 \
  -e TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-personal \
  -- npx @overpod/mcp-telegram

每个账号都有自己的会话文件，不会发生冲突。

多个 Agent / 并发客户端（共享守护进程）

与多个账号相反：一个账号同时由多个客户端操控——例如多个 Claude Code 窗口、并行子 Agent 或多个 IDE。通常，每个进程都会打开同一个会话，导致它们相互挤掉对方，并触发 AUTH_KEY_DUPLICATED。服务模式可以解决这个问题。

运行一个持久的守护进程，由它管理唯一的 Telegram 连接。其他进程都会自动检测到该守护进程（通过 PID 锁），并成为精简客户端，通过本地 Unix 套接字将工具调用转发给它：

# On the host, once: start the daemon (owns the connection, no stdio)
TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH mcp-telegram serve
# (or set MCP_TELEGRAM_DAEMON=1 instead of the `serve` argument)

然后让每个 MCP 客户端使用相同的安装路径和相同的 TELEGRAM_SESSION_PATH，但不传入 serve 参数。它们会自动连接到守护进程；关闭任何客户端都不会断开共享连接。凭据只需提供给守护进程（所有者），因此客户端命令可以省略 TELEGRAM_API_ID/TELEGRAM_API_HASH，并将其保存在守护进程运行的位置。

请参阅**共享守护进程指南**，了解 systemd 单元和 SSH 用法。

代理支持

如果 Telegram 被屏蔽，或者你在容器化环境（Docker、K3s）中运行，请使用 SOCKS5 或 MTProxy：

# SOCKS5 proxy
TELEGRAM_PROXY_IP=127.0.0.1 \
TELEGRAM_PROXY_PORT=10808 \
npx @overpod/mcp-telegram

# MTProxy
TELEGRAM_PROXY_IP=proxy.example.com \
TELEGRAM_PROXY_PORT=443 \
TELEGRAM_PROXY_SECRET=ee00000000000000000000000000000000 \
npx @overpod/mcp-telegram

变量	描述
TELEGRAM_PROXY_IP	代理服务地址
TELEGRAM_PROXY_PORT	代理服务端口
TELEGRAM_PROXY_SOCKS_TYPE	4 或 5（默认值：5）
TELEGRAM_PROXY_SECRET	MTProxy 密钥（启用 MTProxy 模式）
TELEGRAM_PROXY_USERNAME	可选的代理身份验证
TELEGRAM_PROXY_PASSWORD	可选的代理身份验证

通过 WSS 连接（端口 443）

如果你的 VPS 或托管服务 IP 可通过出站端口 443 访问，但无法通过默认的 MTProto 端口 80 访问（某些云服务提供商会出于防滥用策略，禁止访问 Telegram DC IP 段的端口 80），请设置：

TELEGRAM_USE_WSS=true npx @overpod/mcp-telegram

变量	描述
TELEGRAM_USE_WSS	设为 true 时，gramJS 会使用端口 443 而非 80 进行 MTProto TCPFull 传输。默认值：false。不能与 TELEGRAM_PROXY_* 同时使用（gramJS 限制）——如果同时设置，会忽略 useWSS，优先使用代理（并记录警告）。

安装选项

npx（推荐，无需安装）

无需克隆或安装任何内容。直接使用 npx @overpod/mcp-telegram 即可。

全局安装

npm install -g @overpod/mcp-telegram
mcp-telegram          # run server
mcp-telegram login    # QR login

预构建二进制文件（无需运行时）

从 Releases 下载——独立的单文件二进制文件，无任何依赖：

平台	服务端	登录 CLI
Linux x64	mcp-telegram-linux-x64	mcp-telegram-login-linux-x64
Linux ARM64	mcp-telegram-linux-arm64	mcp-telegram-login-linux-arm64
macOS x64	mcp-telegram-darwin-x64	mcp-telegram-login-darwin-x64
macOS ARM64	mcp-telegram-darwin-arm64	mcp-telegram-login-darwin-arm64
Windows x64	mcp-telegram-windows-x64.exe	mcp-telegram-login-windows-x64.exe

# Download (example for Linux x64)
curl -L -o mcp-telegram https://github.com/mcp-telegram/mcp-telegram/releases/latest/download/mcp-telegram-linux-x64
curl -L -o mcp-telegram-login https://github.com/mcp-telegram/mcp-telegram/releases/latest/download/mcp-telegram-login-linux-x64
chmod +x mcp-telegram mcp-telegram-login

# Login
TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH ./mcp-telegram-login

# Run
./mcp-telegram

从源代码安装

git clone https://github.com/mcp-telegram/mcp-telegram.git
cd mcp-telegram
npm install && npm run build

Docker

docker build -t mcp-telegram https://github.com/mcp-telegram/mcp-telegram.git

登录（需要交互式终端）：

docker run -it --rm \
  -e TELEGRAM_API_ID=YOUR_ID \
  -e TELEGRAM_API_HASH=YOUR_HASH \
  -v ~/.mcp-telegram:/root/.mcp-telegram \
  --entrypoint node mcp-telegram dist/qr-login-cli.js

运行 MCP 服务：

docker run -i --rm \
  -e TELEGRAM_API_ID=YOUR_ID \
  -e TELEGRAM_API_HASH=YOUR_HASH \
  -v ~/.mcp-telegram:/root/.mcp-telegram \
  mcp-telegram

注意：必须先通过终端登录一次。之后，会话会保存在 ~/.mcp-telegram 中，并自动重复使用。

在 MCP 客户端中使用

Claude Code（CLI）

claude mcp add telegram -s user \
  -e TELEGRAM_API_ID=YOUR_ID \
  -e TELEGRAM_API_HASH=YOUR_HASH \
  -- npx @overpod/mcp-telegram

Claude Desktop

1. 打开配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

2. 添加 Telegram 服务：

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["@overpod/mcp-telegram"],
      "env": {
        "TELEGRAM_API_ID": "YOUR_ID",
        "TELEGRAM_API_HASH": "YOUR_HASH"
      }
    }
  }
}

3. 重启 Claude Desktop。

4. 询问 Claude：“运行 telegram-login”——此时会显示一个二维码。如果看不到图片，也可以在 ~/.mcp-telegram/qr-login.png 找到。使用 Telegram 扫描二维码（设置 > 设备 > 关联桌面设备）。

5. 询问 Claude：“运行 telegram-status”，以验证连接。

注意：无需使用终端！整个登录过程都可以通过 Claude Desktop 完成。

Claude Desktop（Binary）

设置方法相同，但使用预构建的二进制文件，而不是 npx：

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/mcp-telegram",
      "env": {
        "TELEGRAM_API_ID": "YOUR_ID",
        "TELEGRAM_API_HASH": "YOUR_HASH"
      }
    }
  }
}

Claude Desktop（Docker）

1. 先通过终端登录（请参阅上文的 Docker 部分）。

2. 添加到配置文件中：

{
  "mcpServers": {
    "telegram": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "TELEGRAM_API_ID=YOUR_ID",
        "-e", "TELEGRAM_API_HASH=YOUR_HASH",
        "-v", "~/.mcp-telegram:/root/.mcp-telegram",
        "mcp-telegram"
      ]
    }
  }
}

3. 重启 Claude Desktop。询问 Claude：“运行 telegram-status”，以验证连接。

Cursor / VS Code

将上述相同的 JSON 配置添加到 MCP 设置中（Cursor 设置 > MCP，或 VS Code MCP 配置）。

Mastra

import { MCPClient } from "@mastra/mcp";

const telegramMcp = new MCPClient({
  id: "telegram-mcp",
  servers: {
    telegram: {
      command: "npx",
      args: ["@overpod/mcp-telegram"],
      env: {
        TELEGRAM_API_ID: process.env.TELEGRAM_API_ID!,
        TELEGRAM_API_HASH: process.env.TELEGRAM_API_HASH!,
      },
    },
  },
});

工具

所有工具都可通过 MCP 自动发现——连接后，你的 AI 客户端会看到包含参数和说明的完整列表。

类别	工具
身份验证	telegram-status、telegram-login、telegram-logout
消息	telegram-send-message（包括用于逐字引用回复的 quoteText 和 Premium 消息 effect）、telegram-edit-message、telegram-delete-message、telegram-forward-message、telegram-send-scheduled、telegram-send-typing、telegram-translate-message、telegram-get-message-link
定时消息	telegram-get-scheduled、telegram-delete-scheduled
读取	telegram-list-chats、telegram-read-messages、telegram-search-messages、telegram-search-global、telegram-search-chats、telegram-get-unread、telegram-mark-as-read、telegram-get-replies、telegram-get-unread-mentions、telegram-get-unread-reactions、telegram-get-saved-dialogs
草稿	telegram-save-draft、telegram-get-drafts、telegram-clear-drafts
论坛主题	telegram-list-topics、telegram-read-topic-messages、telegram-create-topic、telegram-edit-topic、telegram-delete-topic
投票	telegram-create-poll
投票交互（v1.31.0）	telegram-vote-poll、telegram-get-poll-results、telegram-get-poll-voters、telegram-close-poll
回应	telegram-send-reaction、telegram-get-reactions、telegram-set-default-reaction、telegram-get-top-reactions、telegram-get-recent-reactions
付费回应（v1.31.0）	telegram-send-paid-reaction（★ Stars）、telegram-toggle-paid-reaction-privacy、telegram-get-paid-reaction-privacy
音频转录（v1.31.0）	telegram-transcribe-audio（Premium）、telegram-get-transcription、telegram-rate-transcription
事实核查（v1.31.0）	telegram-get-fact-check、telegram-edit-fact-check、telegram-delete-fact-check
贴纸	telegram-send-sticker、telegram-get-installed-stickers、telegram-get-recent-stickers、telegram-get-sticker-set、telegram-search-sticker-sets
媒体	telegram-send-file、telegram-download-media、telegram-get-profile-photo、telegram-get-web-preview
富媒体发送	telegram-send-voice、telegram-send-video-note（圆形视频）、telegram-send-location（静态或实时）、telegram-send-venue、telegram-send-contact、telegram-send-dice（🎲🎯🎰🏀⚽🎳）、telegram-send-album（2–10 张分组照片/视频）
群组	telegram-create-group、telegram-edit-group、telegram-invite-to-group、telegram-join-chat、telegram-leave-group、telegram-kick-user、telegram-ban-user、telegram-unban-user、telegram-set-admin、telegram-remove-admin、telegram-get-my-role、telegram-set-chat-permissions、telegram-set-slow-mode、telegram-get-admin-log
聊天信息	telegram-get-chat-info、telegram-get-chat-members、telegram-get-chat-folders
文件夹（v1.33.0）	telegram-create-folder、telegram-edit-folder、telegram-delete-folder、telegram-reorder-folders、telegram-get-suggested-folders、telegram-toggle-folder-tags
全局隐私（v1.33.0）	telegram-get-global-privacy-settings、telegram-set-global-privacy-settings
邀请链接	telegram-create-invite-link、telegram-get-invite-links、telegram-revoke-invite-link
联系人	telegram-get-contacts、telegram-add-contact、telegram-get-contact-requests
管理	telegram-block-user、telegram-unblock-user、telegram-report-spam
个人资料（读取）	telegram-get-profile、telegram-update-profile
个人资料（写入，v1.32.0）	telegram-set-emoji-status（Premium）、telegram-list-emoji-statuses、telegram-clear-recent-emoji-statuses、telegram-set-profile-color（Premium）、telegram-set-birthday、telegram-set-personal-channel、telegram-set-profile-photo、telegram-delete-profile-photo
账户	telegram-get-sessions、telegram-terminate-session、telegram-set-privacy、telegram-set-auto-delete
置顶	telegram-pin-message、telegram-unpin-message
聊天设置	telegram-mute-chat、telegram-archive-chat、telegram-pin-chat、telegram-mark-dialog-unread
管理员开关	telegram-toggle-channel-signatures、telegram-toggle-anti-spam、telegram-toggle-forum-mode、telegram-toggle-prehistory-hidden、telegram-set-chat-reactions、telegram-approve-join-request
统计	telegram-get-broadcast-stats、telegram-get-megagroup-stats
内联机器人和按钮	telegram-inline-query、telegram-inline-query-send、telegram-press-button、telegram-get-message-buttons
实时轮询	telegram-get-state、telegram-get-updates、telegram-get-channel-updates
故事（读取）	telegram-get-all-stories、telegram-get-peer-stories、telegram-get-stories-by-id、telegram-get-story-views
故事（写入，v1.30.0）	telegram-send-story、telegram-edit-story、telegram-delete-stories、telegram-react-to-story、telegram-export-story-link、telegram-read-stories、telegram-toggle-story-pinned、telegram-toggle-story-pinned-to-top、telegram-activate-stealth-mode（Premium）、telegram-get-stories-archive、telegram-report-story
讨论（v1.30.0）	telegram-get-discussion-message、telegram-get-groups-for-discussion
已读回执（v1.30.0）	telegram-get-message-read-participants、telegram-get-outbox-read-date
Boost	telegram-get-my-boosts、telegram-get-boosts-status、telegram-get-boosts-list
商务（v1.32.0）	telegram-get-business-chat-links、telegram-create-business-chat-link、telegram-edit-business-chat-link、telegram-delete-business-chat-link、telegram-resolve-business-chat-link、telegram-set-business-hours、telegram-set-business-location、telegram-set-business-greeting、telegram-set-business-away、telegram-set-business-intro
选择启用（由环境变量控制）	telegram-get-group-call、telegram-get-group-call-participants（需要 MCP_TELEGRAM_ENABLE_GROUP_CALLS=1）；Stars 和礼物：telegram-get-stars-status、telegram-get-stars-transactions、telegram-get-stars-topup-options、telegram-get-stars-subscriptions、telegram-change-stars-subscription、telegram-get-available-star-gifts、telegram-get-saved-star-gifts、telegram-save-star-gift、telegram-convert-star-gift（需要 MCP_TELEGRAM_ENABLE_STARS=1）；telegram-get-quick-replies、telegram-get-quick-reply-messages（需要 MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1）

提示：向 AI 助手询问 “有哪些 Telegram 工具可用？”，即可获取包含参数和描述的完整列表。

可选功能

某些工具默认处于禁用状态，必须通过环境变量选择启用：

变量	值	已启用的工具
MCP_TELEGRAM_ENABLE_GROUP_CALLS	1	telegram-get-group-call、telegram-get-group-call-participants
MCP_TELEGRAM_ENABLE_STARS	1	Stars 余额和交易、充值选项、订阅以及 Star Gifts（浏览 / 保存 / 转换）
MCP_TELEGRAM_ENABLE_QUICK_REPLIES	1	telegram-get-quick-replies、telegram-get-quick-reply-messages

将这些内容添加到 .env 文件或 MCP 客户端配置中即可启用。

开发

npm run dev        # Start with file watching (tsx)
npm start          # Start the MCP server
npm run login      # QR code login in terminal
npm run build      # Compile TypeScript
npm run lint       # Check code with Biome
npm run lint:fix   # Auto-fix lint issues
npm run format     # Format code with Biome

项目结构

src/
  index.ts            -- MCP server entry point
  telegram-client.ts  -- TelegramService class (GramJS wrapper)
  qr-login-cli.ts     -- CLI utility for QR code login
  tools/              -- Modular tool definitions
    auth.ts           -- Connection & login
    messages.ts       -- Send, read, search, edit, delete, forward; inline bots; real-time polling
    chats.ts          -- Chat listing, group management, admin toggles, stats
    contacts.ts       -- Contacts, profiles, moderation
    media.ts          -- Files, photos, downloads
    reactions.ts      -- Reactions, set-chat-reactions
    extras.ts         -- Pin, schedule, polls, topics
    stickers.ts       -- Sticker sets, send, search, browse
    account.ts        -- Sessions, privacy, auto-delete, profile, emoji status, birthday, chat mute/folders, invite links
    business.ts       -- Telegram Business: chat links CRUD, work hours, location, greeting/away/intro
    boosts.ts         -- Boost status, my boosts, boosters list
    stories.ts        -- Stories: list all, peer, by-id, view stats
    group-calls.ts    -- Group call info and participants (opt-in: MCP_TELEGRAM_ENABLE_GROUP_CALLS)
    stars.ts          -- Stars wallet status and transactions (opt-in: MCP_TELEGRAM_ENABLE_STARS)
    quick-replies.ts  -- Quick replies and messages (opt-in: MCP_TELEGRAM_ENABLE_QUICK_REPLIES)
    shared.ts         -- Shared utilities

技术栈

• TypeScript -- ES2022、ESM 模块
• GramJS (telegram) -- Telegram MTProto 客户端
• @modelcontextprotocol/sdk -- MCP 服务框架
• Zod -- 工具参数的运行时架构验证
• Biome -- 代码检查和格式化工具
• tsx -- 无需构建步骤即可执行 TypeScript
• dotenv -- 环境变量管理

故障排除

AUTH_KEY_DUPLICATED

Telegram 会话一次只能由一个进程使用。如果遇到 AUTH_KEY_DUPLICATED，说明另一个进程正在使用同一个会话文件。

解决方案：为每个环境创建单独的会话：

# Local development
TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-local npx @overpod/mcp-telegram login

# Production server
TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-prod npx @overpod/mcp-telegram login

然后在每个环境的 MCP 配置中相应地设置 TELEGRAM_SESSION_PATH。

安全

• API 凭据存储在 .env 中（已加入 gitignore）
• 会话存储在 ~/.mcp-telegram/session 中，权限为 0600（仅所有者可访问）
• 会话目录以 0700 权限创建
• 无需电话号码——仅通过 QR 码进行身份验证
• 不会向第三方服务发送数据——所有通信均通过 MTProto 直接发送到 Telegram 服务器
• QR 登录码在本地生成，不会离开你的设备
• 每个进程使用一个会话——在多个进程中同时使用同一个会话会导致 AUTH_KEY_DUPLICATED 错误（参见故障排除）
• 这是一个用户机器人（个人账号），而非机器人——请遵守 Telegram 服务条款

许可证

MIT