使用说明
电报MCP服务器
功能齐全 模型上下文协议（MCP） 将AI助手连接到Telegram的服务器。建立在 电视募捐 （MTProto）和 FastMCP，它暴露了 89工具 穿过 13个类别 --为您的AI提供对Telegram帐户的完全读/写访问权限。
与WhatsApp或其他桥接器不同，Telegram在服务器端存储完整的聊天历史记录。此MCP可以从任何对话开始访问每条消息，没有同步限制。
亮点
- 完整聊天记录导出 --通过结构化JSON输出、可选媒体下载和自动速率限制处理提取整个对话
- 媒体下载与管理 --从任何聊天中下载照片、视频、语音信息、文档、贴纸和圆形视频
- 89工具，13分类 --聊天、联系人、消息、媒体、群组、用户资料、反应、草稿、文件夹、隐私、内联按钮、论坛主题和机器人/贴纸
- MTProto直接连接 --没有桥梁，没有机器人，没有中介。通过Telethon直接连接到Telegram的API
- STDIO传输 --通过标准I/O作为本地MCP服务器运行，与Claude Code和任何兼容MCP的客户端兼容
目录
安装
要求： Python 3.10+
# Clone the repository
git clone https://github.com/YOUR_USERNAME/telegram-mcp.git
cd telegram-mcp
# Install with uv (recommended)
uv pip install -e .
# Or with pip
pip install -e .
这将安装 telegram-mcp CLI命令。
电报API证书
- 首选 https://my.telegram.org
- 登录并导航到 API开发工具
- 创建一个新的应用程序来获取您的 API ID 和 API哈希
认证
在使用服务器之前，请验证您的Telegram帐户：
# Create a .env file with your credentials
cat > .env << 'EOF'
TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
TELEGRAM_PHONE_NUMBER=+your_phone_number
TELEGRAM_SESSION_PATH=./telegram
TELEGRAM_DOWNLOAD_DIR=./downloads
EOF
# Run the interactive authentication
python -m telegram_mcp.auth
您将在Telegram应用程序中收到验证码。输入它，并可选择提供您的2FA密码。这创建了一个 telegram.session 用于未来自动身份验证的文件。
配置
| 环境变量 | 描述 | 默认值 |
|---|---|---|
TELEGRAM_API_ID |
电报API ID（必需） | - |
TELEGRAM_API_HASH |
电报API哈希（必需） | - |
TELEGRAM_PHONE_NUMBER |
身份验证电话 | -- |
TELEGRAM_SESSION_PATH |
会话文件的路径（无 .session 扩展） |
./telegram |
TELEGRAM_DOWNLOAD_DIR |
媒体下载的默认目录 | ./downloads |
使用Claude代码
将服务器添加到Claude Code：
claude mcp add telegram-mcp \
-s user \
-e TELEGRAM_API_ID=your_api_id \
-e TELEGRAM_API_HASH=your_api_hash \
-e TELEGRAM_SESSION_PATH=/path/to/telegram \
-e TELEGRAM_DOWNLOAD_DIR=~/Downloads/telegram_downloads \
-- telegram-mcp
验证服务器是否已连接：
claude mcp list
连接后，您可以通过自然语言与Telegram进行交互：
> Show me the last 20 messages from Alice
> Download all photos from "Family Group" for the past week
> Export full chat history with David including all media
> Search for "meeting notes" in group "Work Team"
> Who is in group "Project Alpha"?
> Send "On my way!" to Mom
工具参考
信息（15个工具）
| 工具 | 说明 |
|---|---|
list_messages |
使用分页、日期过滤检索邮件(offset_date)、文本搜索和发件人筛选 |
search_messages |
在任何聊天中进行全文搜索 |
get_message_context |
在特定消息之前/之后获取周围消息 |
send_message |
使用Markdown支持和可选回复发送文本 |
send_file |
发送带有字幕的照片、视频、文档、语音和圆形视频 |
edit_message |
编辑以前发送的消息 |
delete_messages |
使用可选撤销功能删除邮件（为所有人删除） |
forward_message |
将消息转发到另一个聊天室 |
pin_message |
使用可选的静默通知固定消息 |
unpin_message |
取消发送特定或最近的邮件 |
get_pinned_messages |
检索聊天中的所有固定消息 |
mark_read |
将聊天中的所有消息标记为已读 |
send_reaction |
使用表情符号回复消息 |
get_media_info |
在不下载的情况下检查媒体元数据 |
create_poll |
使用匿名/多选模式创建民意调查和测验 |
媒体（3个工具）
| 工具 | 说明 |
|---|---|
download_media |
从消息中下载任何媒体附件（照片、视频、文档、语音、贴纸、圆形视频）。返回包含文件路径、名称和大小的结构化JSON |
download_profile_photo |
下载任何用户、组或频道的个人资料照片 |
export_full_chat_history |
导出整个对话 --所有消息从一开始就具有可选的媒体下载、类型过滤和结构化JSON输出。自动处理速率限制 |
聊天和对话（10个工具）
| 工具 | 说明 |
|---|---|
list_dialogs |
列出按最近活动排序的所有对话，包括文件夹筛选和未读计数 |
get_chat_info |
任何聊天、群组或频道的完整元数据 |
get_direct_chat_by_contact |
查找与特定联系人的DM对话 |
get_contact_chats |
与联系人共享所有聊天记录 |
get_last_interaction |
查找联系人的最后消息日期/详细信息 |
archive_chat |
将对话存档 |
unarchive_chat |
从存档还原 |
mute_chat |
将通知静音 |
unmute_chat |
取消静音通知 |
search_public_chats |
搜索公共频道、组和用户 |
联系人（14个工具）
| 工具 | 说明 |
|---|---|
list_contacts |
列出所有已保存的联系人 |
search_contacts |
按姓名或用户名搜索 |
get_contact_details |
完整用户信息：个人简介、常用聊天记录、阻止状态、个人资料照片 |
get_contact_ids |
获取所有联系人的数字ID |
add_contact |
通过电话号码或用户名添加联系人 |
delete_contact |
删除联系人 |
import_contacts |
从列表中批量导入联系人 |
export_contacts |
将所有联系人导出为JSON格式 |
resolve_username |
解析@username以获取完整的实体详细信息 |
block_user / unblock_user |
阻止或取消阻止用户 |
get_blocklist |
列出所有被阻止的用户 |
群组和频道（21个工具）
| 工具 | 说明 |
|---|---|
create_group |
创建新组或超级组 |
create_channel |
创建广播频道 |
get_group_participants |
列出具有角色的成员（创建者、管理员、成员） |
get_admins |
列出所有管理员 |
add_group_members / remove_group_members |
添加或删除组成员 |
promote_to_admin / demote_admin |
使用自定义标题管理管理员权限 |
ban_user / unban_user |
禁止或取消超级群用户的禁令 |
get_banned_users |
列出被禁止/被踢用户 |
update_group |
更新标题和描述 |
edit_chat_photo / delete_chat_photo |
管理群组/频道照片 |
leave_group |
离开群组或频道 |
subscribe_public_channel |
加入公共频道 |
get_invite_link |
获取当前邀请链接 |
export_chat_invite |
创建带有过期、使用限制和标题的邀请链接 |
import_chat_invite / join_chat_by_link |
通过邀请哈希或链接加入 |
用户资料（7个工具）
| 工具 | 说明 |
|---|---|
get_me |
获取您自己的帐户信息 |
update_profile |
更新名字、姓氏和个人简介 |
set_profile_photo / delete_profile_photo |
管理个人资料照片 |
get_user_status |
查看在线状态（在线、最近、上周等） |
get_user_photos |
获取个人资料照片元数据 |
resolve_username |
将@username解析为实体详细信息 |
反应（3个工具）
| 工具 | 说明 |
|---|---|
send_reaction |
使用表情符号回复消息 |
remove_reaction |
消除你的反应 |
get_message_reactions |
查看所有反应以及谁做出了反应 |
草稿（3个工具）
| 工具 | 说明 |
|---|---|
save_draft |
保存带有可选回复和链接预览控件的消息草稿 |
get_drafts |
获取所有聊天记录中的所有草稿 |
clear_draft |
删除草稿 |
文件夹（7个工具）
| 工具 | 说明 |
|---|---|
list_folders |
列出所有聊天文件夹 |
get_folder |
包含对等列表的详细文件夹信息 |
create_folder |
创建具有丰富过滤选项的文件夹（联系人、群组、频道、机器人程序、排除静音/已读/已存档、表情符号图标） |
delete_folder |
删除文件夹 |
reorder_folders |
重新排序文件夹 |
add_chat_to_folder / remove_chat_from_folder |
管理文件夹内容 |
隐私（2个工具）
| 工具 | 说明 |
|---|---|
get_privacy_settings |
获取以下内容的隐私规则：状态、电话、个人资料照片、转发、通话、P2P通话、群组邀请、个人简介 |
set_privacy_settings |
将规则更新为：允许所有、仅允许联系人或禁止所有 |
内联按钮（2个工具）
| 工具 | 说明 |
|---|---|
list_inline_buttons |
检查消息上的内联键盘按钮（文本、回调、URL） |
press_inline_button |
按文本或索引单击内联按钮，返回机器人回调响应 |
论坛主题（1个工具）
| 工具 | 说明 |
|---|---|
list_topics |
使用搜索和分页功能在超级组中列出论坛主题 |
机器人和贴纸（6工具）
| 工具 | 说明 |
|---|---|
get_bot_info |
获取机器人描述、命令和验证状态 |
set_bot_commands |
为您自己的机器人设置命令 |
get_sticker_sets |
列出已安装的贴纸包 |
send_sticker |
发送贴纸文件（.webp、.tgs、.webm） |
search_gifs |
通过Telegram的内联机器人搜索GIF |
send_gif |
按文档ID发送GIF |
媒体能力
该服务器提供跨Telegram富媒体类型的全面媒体处理：
支持的媒体类型
| 类型 | 下载 | 发送 | 元数据 |
|---|---|---|---|
| 照片 | 是 | 是 | 尺寸、文件大小 |
| 视频 | 是 | 是 | 持续时间、尺寸、编解码器 |
| 语音消息 | 是 | 是 | 持续时间，编解码器 |
| 圆形视频（视频注释） | 是 | 是 | 持续时间、尺寸 |
| 文档/文件 | 是 | 是 | MIME类型、文件名、大小 |
| 贴纸 | 是 | 是 | 表情符号，包装名称，动画/视频 |
| GIF | 是 | 是 | 通过内联机器人搜索 |
| 个人资料照片 | 是 | 是 | 按用户或按组 |
媒体运营
从邮件中下载任何媒体：
download_media(chat_id="123456", message_id=789, output_dir="~/Downloads/export")
→ { "path": "~/Downloads/export/photo_2026-02-15.jpg", "name": "photo_2026-02-15.jpg", "size": 245760 }
检查未下载的媒体：
get_media_info(chat_id="123456", message_id=789)
→ { "type": "video", "duration": 45, "width": 1920, "height": 1080, "mime": "video/mp4", "size": 15728640 }
下载个人资料照片：
download_profile_photo(entity_id="@username", output_dir="~/Downloads/photos")
完整聊天导出
这 export_full_chat_history 该工具专为完整的对话提取而设计——从第一条到最新的每条消息，都有可选的媒体下载。
特性
- 完整历史 --从头到尾迭代整个对话
- 可选媒体下载 --按类型下载所有媒体或过滤器（照片、视频、语音、音频、文档、贴纸）
- 结构化JSON输出 --干净、可解析的输出，包括消息元数据、发件人信息、时间戳和媒体路径
- 自动速率限制 --通过自动重试优雅地处理Telegram的FloodWaitError
- 渐进式进展 --批量处理消息以提高内存效率
用法
export_full_chat_history(
chat_id="1508482670",
output_dir="~/Downloads/telegram_export_alice",
include_media=true,
media_types="photo,voice,document"
)
输出格式
{
"chat_id": "1508482670",
"chat_name": "Alice",
"export_date": "2026-02-15T12:00:00",
"total_messages": 4523,
"messages": [
{
"id": 1,
"date": "2024-03-15T09:30:00+00:00",
"sender_id": 376087036,
"text": "Hey Alice!",
"has_media": false
},
{
"id": 2,
"date": "2024-03-15T09:31:00+00:00",
"sender_id": 1508482670,
"text": "",
"has_media": true,
"media_type": "voice",
"media_path": "~/Downloads/telegram_export_alice/media/voice_2.ogg"
}
],
"media_summary": {
"photo": 156,
"voice": 89,
"document": 23,
"total_downloaded": 268
}
}
目标邮件检索
要进行更有针对性的提取，请使用 list_messages 使用过滤器：
# Messages from a specific sender in the past 7 days
list_messages(chat_id="group_id", from_user="alice", offset_date="2026-02-08T00:00:00", limit=0)
# Search for specific content
search_messages(chat_id="group_id", query="meeting notes", limit=50)
# Get context around a specific message
get_message_context(chat_id="group_id", message_id=12345, before=10, after=10)
克劳德代码技能
这 telegram_claude_skill/ 目录包含一个即用型 Claude代码技能 这使克劳德能够用自然语言访问所有Telegram MCP工具。您可以使用以下对话命令，而不是手动调用工具：
/telegram show conversation with "David" for past 7 days
/telegram download all audio from group "Work Team"
/telegram export full chat history with "Mom"
/telegram search for "deadline" in group "Marketing"
/telegram send "On my way!" to Alice
安装
将技能复制到您的Claude Code技能目录中：
cp -r telegram_claude_skill/ ~/.claude/skills/telegram/
然后在Claude Code中调用它 /telegram <your request>.
该技能的作用是什么
该技能充当编排层，它：
- 解析自然语言 --理解“显示对话”、“下载媒体”、“导出历史记录”、“搜索”、“发送”等意图。
- 解决目标 --按姓名、用户名或电话号码查找联系人/组
- 处理分页 --自动迭代大型消息集
- 下载媒体 --在本地保存照片、视频、语音信息和文档
- 导出结构化JSON --使用媒体摘要生成干净、可解析的对话导出
- 行动前提问 --在发送消息或执行破坏性操作之前始终进行确认
看 telegram_claude_skill/SKILL.md 了解完整的技能定义。
项目结构
telegram-mcp/
├── pyproject.toml # Package configuration & dependencies
├── telegram_mcp/
│ ├── __init__.py
│ ├── server.py # FastMCP server entry point (STDIO transport)
│ ├── client.py # Telethon client singleton manager
│ ├── auth.py # Interactive authentication flow
│ └── tools/ # Tool implementations by category
│ ├── chats.py
│ ├── contacts.py
│ ├── messages.py
│ ├── media.py
│ ├── groups.py
│ ├── user_profile.py
│ ├── reactions.py
│ ├── drafts.py
│ ├── folders.py
│ ├── privacy.py
│ ├── buttons.py
│ ├── topics.py
│ ├── bots.py
│ └── stickers.py
├── telegram_claude_skill/ # Claude Code skill for natural language access
│ └── SKILL.md
├── tests/
└── scripts/
└── authenticate.py
发展
# Install in development mode
uv pip install -e ".[dev]"
# Run tests
pytest tests/
# Run the server directly
python -m telegram_mcp.server
# Or via the CLI entry point
telegram-mcp
依赖项
| 包装 | 用途 |
|---|---|
| 长时间的电视节目 | Telegram MTProto客户端 |
| fastmcp | MCP服务器框架 |
| 皮丹提克 | 数据验证 |
| python dotenv | 环境变量加载 |
| aiofiles | 异步文件I/O |
| 密码 | 加密加速 |
贡献
该项目正在积极维护，欢迎捐款。
如果您遇到错误、意外行为或有改进想法，无论是在 MCP服务器 本身或 Claude代码技能 --请不要犹豫：
- 提出问题 描述你遇到的或你想看到的
- 提交拉取请求 进行修复或增强
即使是一些小事情也有帮助：返回意外输出的工具、丢失的边缘案例、技能文件中更好的提示，或者Telegram API的更改破坏了一些东西。如果你不确定某件事是错误还是只是你的设置，无论如何都要打开一个问题——我们会一起解决的。
许可证
麻省理工学院
