# Telegram MCP

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

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

## 1. 安装

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

## 2. 申请 API 凭据

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

```
TELEGRAM_API_ID=1234567
TELEGRAM_API_HASH=xxxxxxxxxxxxxxxx
```

## 3. 登录（只需一次）

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

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

## 4. 接入 MCP 客户端

Claude Code：

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

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

```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()` 异步函数即可，导入时自动注册。

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

```powershell
.\.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；开启需要在客户端里手动打开，且群成员数达标。

---

Copyright (c) 2026 Anonymouse8882

Source Repository:
[https://github.com/Anonymouse8882/TelegamMCP](https://github.com/Anonymouse8882/TelegamMCP)

Licensed under GPL v3.