Telegram MCP

一个基于 MTProto 用户账号（Telethon）的 MCP server，让 Claude 等 MCP 客户端可以读写你的 Telegram：浏览对话、读历史消息、全局搜索、收发消息与文件、投票、贴纸、群管理、和 bot 交互。共 85 个工具。

⚠️ 它以你本人的账号登录，权限等同于你自己的 Telegram 客户端。会话文件（~/.telegram-mcp/session.txt）等同于账号凭据，切勿分享或提交到版本库。自动化行为过于频繁可能触发 Telegram 的风控/封号策略。

1. 安装

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .

2. 申请 API 凭据

到 https://my.telegram.org/apps 登录并创建一个 app，拿到 api_id 和 api_hash。复制 .env.example 为 .env 并填入：

TELEGRAM_API_ID=1234567
TELEGRAM_API_HASH=xxxxxxxxxxxxxxxx

3. 登录（只需一次）

.\.venv\Scripts\python.exe -m telegram_mcp.login

按提示输入手机号（带国家码，如 +8613800138000）、Telegram 发来的验证码，以及二步验证密码（如果开了的话）。成功后会话会写入 ~/.telegram-mcp/session.txt。

4. 接入 MCP 客户端

Claude Code：

claude mcp add telegram -- C:\Users\Anonymouse\Projects\TelegamMCP\.venv\Scripts\python.exe -m telegram_mcp.server

或手写配置（claude_desktop_config.json / .mcp.json）：

{
  "mcpServers": {
    "telegram": {
      "command": "C:\\Users\\Anonymouse\\Projects\\TelegamMCP\\.venv\\Scripts\\python.exe",
      "args": ["-m", "telegram_mcp.server"],
      "env": {
        "TELEGRAM_API_ID": "1234567",
        "TELEGRAM_API_HASH": "xxxxxxxxxxxxxxxx"
      }
    }
  }
}

工具一览

账号与联系人

工具	说明
`get_me`	当前账号信息
`update_profile`	改名字 / 姓氏 / 简介
`set_username`	设置或清空 @username
`set_profile_photo`	用本地图片换头像
`list_contacts` / `search_contacts`	联系人与公开实体搜索
`add_contact` / `delete_contact`	加/删通讯录（支持只有手机号的情况）
`block_user` / `list_blocked`	拉黑、取消拉黑、看黑名单

对话

工具	说明
`list_dialogs`	聊天列表，可按类型（含 bot）/未读/归档/名字过滤
`get_chat_info`	对话详情（简介、成员数、置顶、是否话题群等）
`get_participants`	成员列表，可只看管理员 / bot / 被封禁的人
`get_common_chats`	和某人的共同群组
`list_folders`	聊天文件夹及其包含的对话
`archive_chat` / `pin_chat`	归档、置顶对话
`mute_chat` / `mark_chat_unread`	免打扰、标记未读
`join_chat` / `leave_chat`	加入 / 退出群频道（支持 t.me/+ 邀请链接）

读消息

工具	说明
`get_messages`	读历史，支持分页、发送者过滤、话题、时间点
`get_message_context`	取某条消息前后各 N 条，看上下文
`search_messages`	关键词搜索，不指定 chat 即全局；可按媒体类型筛
`get_media_messages`	按媒体类型筛选（图片/视频/文件/语音/链接/GIF）
`get_pinned_messages`	置顶消息
`get_unread_summary`	未读概览
`get_message_reactions`	一条消息的表情回应明细（谁点了什么）
`get_replies`	频道帖子的评论区 / 某条消息的回复串
`get_forum_topics`	话题群的话题列表
`get_scheduled_messages`	自己设置的定时消息
`get_message_link` / `resolve_message_link`	生成 t.me 链接 / 从链接反查消息
`wait_for_message`	轮询等待新消息（给 bot 发指令后等回复）

发消息

工具	说明
`send_message`	发文本，支持回复/静默/Markdown/定时/频道评论
`send_file` / `send_album`	发单个文件，或一次发一整组（最多 10 个）
`send_sticker`	从贴纸包里发贴纸（按 index 或 emoji 选）
`send_poll` / `vote_poll` / `close_poll`	发起投票或测验、投票、关闭投票
`send_location` / `send_contact` / `send_dice`	位置或地点卡片、联系人卡片、骰子动画
`send_typing`	显示"正在输入…"状态
`edit_message`	编辑自己的消息（也可改媒体说明文字）
`delete_messages`	删除消息（`revoke` 双向删除，不可恢复）
`forward_messages`	转发，`as_copy=True` 可去掉"转发自"抬头
`forward_media_to_saved`	一键存到收藏夹
`mark_as_read` / `pin_message` / `send_reaction`	已读、置顶、表情回应
`send_scheduled_now` / `delete_scheduled_messages`	立刻发出 / 取消定时消息
`delete_chat_history`	清空聊天记录（需 `confirm=True`）

媒体

工具	说明
`download_media`	下载某条消息的媒体
`download_chat_media`	批量下载一个对话里最近的媒体，可限体积
`get_file_info`	只看文件名/大小/时长/分辨率，不下载
`get_profile_photos` / `download_profile_photo`	头像列表与下载
`list_sticker_sets` / `get_sticker_set`	自己的贴纸包、某个包里的贴纸

群 / 频道管理

工具	说明
`create_group` / `create_channel`	建超级群、旧式小群或广播频道
`add_participants` / `kick_participant`	拉人 / 踢人
`ban_participant` / `restrict_participant`	封禁、禁言（可设到期时间，如 `+7d`）
`set_default_permissions`	全群默认权限
`promote_admin`	任命 / 撤销管理员，可设自定义头衔
`set_chat_title` / `set_chat_about` / `set_chat_photo`	改群名、简介、头像
`export_invite_link`	生成邀请链接（可设有效期、次数、需审批）
`set_slow_mode`	慢速模式
`get_admin_log`	管理操作日志
`create_forum_topic` / `edit_forum_topic`	新建 / 修改话题
`delete_chat`	删除群或频道（需 `confirm=True`）

与 Bot 交互

工具	说明
`get_bot_commands`	获取一个 bot 的 `/命令` 菜单、简介、菜单按钮
`start_bot`	发 `/start`（可带 deep link 参数）并等回复
`click_inline_button`	点击 inline 按钮，可按 `data` / `data_hex` / `text` 定位
`press_reply_keyboard`	按下"回复键盘"上的按钮（本质是发送对应文字）
`inline_query`	向 bot 发 inline 查询（`@bot 关键词`），可直接发送某条结果
`quote_sticker`	把消息转发给 @QuotLyBot 生成引用贴纸（内容会经过第三方服务器）

消息返回结果里若带按钮，会在 reply_markup 字段下列出 rows 和每个按钮的 kind、 text、data(callback) / url(链接) / query(switch_inline) 等，方便定位。

安全开关

TELEGRAM_READ_ONLY=1 — 一键禁用所有写工具。
不可恢复的操作（delete_chat_history、delete_chat）必须显式传 confirm=True，第一次不传会返回提示而不执行。
delete_messages(revoke=True) 会为对方一起删除，调用前请先跟用户确认。

参数写法

chat：123456789、-1001234567890、@username、username、https://t.me/username、 me（收藏夹）都能识别。纯数字 ID 需要客户端"见过"该实体（先跑一次 list_dialogs 即可）。

时间（schedule_at / until / expires_at / before）：相对时间 +30m、+2h、+7d，ISO 8601 2026-01-01T09:00:00，或 Unix 时间戳。

代码结构

telegram_mcp/
  app.py           共享的 FastMCP 实例、配置、时间解析等 helper
  client.py        Telethon 客户端单例与 chat 参数归一化
  serializers.py   Telethon 对象 -> LLM 友好的 dict
  server.py        入口（python -m telegram_mcp.server）
  tools/
    account.py     账号、联系人、黑名单
    dialogs.py     对话列表与对话级设置
    messages.py    消息读写、投票、定时、等待
    media.py       文件、贴纸、头像
    admin.py       建群、成员与权限、话题
    bots.py        bot 指令、按钮、inline 查询

新增工具只要在 tools/ 下的模块里写一个 @mcp.tool() 异步函数即可，导入时自动注册。

自检（只读，不会发送/修改任何东西）：

.\.venv\Scripts\python.exe scripts\smoke_read.py

常见问题

尚未登录 — 跑第 3 步的 login 脚本。
无法解析对话 — 先 list_dialogs 或 search_contacts 拿到 @username / 正确 ID。
Could not find the input entity — 同上，Telethon 需要先缓存实体。
FloodWaitError — 请求过快被限流，等待提示的秒数后再试。
PremiumAccountRequiredError — 该动作（如给自己的收藏夹消息加表情）需要 Telegram Premium。
话题相关报错 — 目标群没开 Topics；开启需要在客户端里手动打开，且群成员数达标。

Source Repository: https://github.com/Anonymouse8882/TelegamMCP

Licensed under GPL v3.