---

🤖 MCP实战

以下是Claude中Telegram MCP功能的演示（参考Anthropic文档）：

基本使用示例：

1. 示例：让Claude分析聊天记录并发送回复：

2. 成功向群组发送消息：

正如你所见，AI可以无缝地与你的Telegram账号交互，以自然的方式获取并展示你的聊天、消息及其他数据。

---

一个功能齐全的Telegram集成工具，适用于Claude、Cursor以及任何兼容MCP的客户端，由Telethon和模型上下文协议(MCP)提供支持。该项目使你能够以编程方式与Telegram账号互动，自动化从消息发送到群组管理的各项操作。

---

🚀 功能与工具

该MCP服务器提供了庞大的Telegram工具集。所有主要的Telegram/Telethon功能都可作为工具使用！

聊天与群组管理

• get_chats(page, page_size)：分页显示聊天列表
• list_chats(chat_type, limit)：按元数据和筛选条件列出聊天
• get_chat(chat_id)：获取聊天的详细信息
• create_group(title, user_ids)：创建新群组
• invite_to_group(group_id, user_ids)：邀请用户加入群组或频道
• create_channel(title, about, megagroup)：创建频道或超级群组
• edit_chat_title(chat_id, title)：更改聊天/群组/频道标题
• delete_chat_photo(chat_id)：移除聊天/群组/频道头像
• leave_chat(chat_id)：退出群组或频道
• get_participants(chat_id)：列出所有参与者
• get_admins(chat_id)：列出所有管理员
• get_banned_users(chat_id)：列出所有被禁用的用户
• promote_admin(chat_id, user_id)：将用户提升为管理员
• demote_admin(chat_id, user_id)：将管理员降级为普通用户
• ban_user(chat_id, user_id)：封禁用户
• unban_user(chat_id, user_id)：解封用户
• get_invite_link(chat_id)：获取邀请链接
• export_chat_invite(chat_id)：导出邀请链接
• import_chat_invite(hash)：通过邀请哈希加入聊天
• join_chat_by_link(link)：通过邀请链接加入聊天
• subscribe_public_channel(channel)：通过用户名或ID订阅公开频道或超级群组

消息发送

• get_messages(chat_id, page, page_size)：分页显示消息
• list_messages(chat_id, limit, search_query, from_date, to_date)：筛选消息
• list_topics(chat_id, limit, offset_topic, search_query)：列出超级群组中的论坛主题
• send_message(chat_id, message)：发送消息
• reply_to_message(chat_id, message_id, text)：回复消息
• edit_message(chat_id, message_id, new_text)：编辑自己的消息
• delete_message(chat_id, message_id)：删除消息
• forward_message(from_chat_id, message_id, to_chat_id)：转发消息
• pin_message(chat_id, message_id)：置顶消息
• unpin_message(chat_id, message_id)：取消置顶
• mark_as_read(chat_id)：标记全部消息为已读
• get_message_context(chat_id, message_id, context_size)：获取消息周围的上下文
• get_history(chat_id, limit)：获取完整的聊天记录
• get_pinned_messages(chat_id)：列出所有置顶消息
• get_last_interaction(contact_id)：获取与联系人的最新消息
• create_poll(chat_id, question, options, multiple_choice, quiz_mode, public_votes, close_date)：创建投票
• list_inline_buttons(chat_id, message_id, limit)：查看内联键盘以发现按钮文本/索引
• press_inline_button(chat_id, message_id, button_text, button_index)：通过标签或索引触发内联键盘回调
• send_reaction(chat_id, message_id, emoji, big=False)：为消息添加反应
• remove_reaction(chat_id, message_id)：移除消息上的反应
• get_message_reactions(chat_id, message_id, limit=50)：获取消息的所有反应

联系人管理

• list_contacts()：列出所有联系人
• search_contacts(query)：搜索联系人
• add_contact(phone, first_name, last_name)：添加联系人
• delete_contact(user_id)：删除联系人
• block_user(user_id)：阻止用户
• unblock_user(user_id)：解除阻止
• import_contacts(contacts)：批量导入联系人
• export_contacts()：将所有联系人导出为JSON文件
• get_blocked_users()：列出被阻止的用户
• get_contact_ids()：列出所有联系人ID
• get_direct_chat_by_contact(contact_query)：查找与特定联系人的直接聊天
• get_contact_chats(contact_id)：列出与特定联系人的所有聊天

用户与个人资料

• get_me()：获取你的用户信息
• update_profile(first_name, last_name, about)：更新个人资料
• set_profile_photo(file_path)：从允许的根目录设置头像
• delete_profile_photo()：移除头像
• get_user_photos(user_id, limit)：获取用户的个人资料照片
• get_user_status(user_id)：获取用户的在线状态

媒体

• get_media_info(chat_id, message_id)：获取消息中媒体的相关信息
• send_file(chat_id, file_path, caption)：从允许的根目录发送本地文件
• download_media(chat_id, message_id, file_path)：将消息中的媒体保存到允许的根目录下
• upload_file(file_path)：上传本地文件并返回上传元数据
• send_voice(chat_id, file_path)：从允许的根目录发送.ogg/.opus语音消息
• send_sticker(chat_id, file_path)：从允许的根目录发送.webp贴纸
• edit_chat_photo(chat_id, file_path)：从允许的根目录更新聊天头像

搜索与发现

• search_public_chats(query, limit)：搜索公开聊天/频道/机器人，结果数量可配置
• search_messages(chat_id, query, limit)：在聊天中搜索消息
• search_global(query, page, page_size)：全球范围内分页搜索消息
• resolve_username(username)：将用户名解析为ID

贴纸、GIF、机器人

• get_sticker_sets(): 列出贴纸集
• get_bot_info(bot_username): 获取机器人信息
• set_bot_commands(bot_username, commands): 设置机器人命令（仅限机器人账号）

隐私、设置及其他

• get_privacy_settings(): 获取隐私设置
• set_privacy_settings(key, allow_users, disallow_users): 设置隐私设置
• mute_chat(chat_id): 静音通知
• unmute_chat(chat_id): 取消静音通知
• archive_chat(chat_id): 归档聊天
• unarchive_chat(chat_id): 取消归档聊天
• get_recent_actions(chat_id): 获取最近的管理员操作

草稿

• save_draft(chat_id, message, reply_to_msg_id, no_webpage): 将草稿消息保存到聊天或频道
• get_drafts(): 获取所有聊天中的所有草稿消息
• clear_draft(chat_id): 清除/删除特定聊天中的草稿

输入验证

为提高健壮性，所有接受 chat_id 或 user_id 参数的函数现在都包含输入验证。您可以使用以下任意格式来提供这些 ID：

• 整数 ID：用户、聊天或频道的直接整数 ID（例如 123456789 或 -1001234567890）。
• 字符串 ID：以字符串形式提供的整数 ID（例如 "123456789"）。
• 用户名：用户或频道的公开用户名（例如 "@username" 或 "username"）。

服务器会自动验证输入并将其转换为正确的格式，然后再向 Telegram 发送请求。如果输入无效，则会返回明确的错误信息。

文件路径工具安全模型

文件路径工具现已可用，但默认处于禁用状态，直到配置了允许的根目录。

支持的文件路径工具：

• send_file, download_media, set_profile_photo, edit_chat_photo, send_voice, send_sticker, upload_file

安全语义（与 MCP 文件系统服务器一致）：

• 服务器端白名单通过 CLI 位置参数实现（当 Roots API 不受支持时作为后备）。
• 当客户端提供的 MCP Roots 可用时，将替换服务器端白名单。
• 如果客户端返回空的 Roots 列表，则文件路径工具将被禁用（拒绝所有）。
• 所有路径都会通过 realpath 解析，并且必须位于允许的根目录内。
• 拒绝遍历或类似 glob 的模式（..、*、?、~ 等）。
• 相对路径会解析到第一个允许的根目录下。
• 写入工具在未指定 file_path 时，默认会将文件保存到 <first_root>/downloads/。

示例服务器启动命令，包含已列入白名单的根目录：

uv --directory /full/path/to/telegram-mcp run main.py /data/telegram /tmp/telegram-mcp

目前 GIF 工具功能有限：get_gif_search 和 send_gif 可用，而由于 Telethon/Telegram API 交互的可靠性限制，get_saved_gifs 尚未实现。

---

📋 需求

• Python 3.10+
• Telethon
• MCP Python SDK
• Claude Desktop 或 Cursor（或任何 MCP 客户端）

---

🔧 安装与设置

1. 分支并克隆

git clone https://github.com/chigwell/telegram-mcp.git
cd telegram-mcp

2. 使用 uv 安装依赖

uv sync

3. 生成会话字符串

uv run session_string_generator.py

按照提示进行身份验证，并更新你的 .env 文件。

4. 配置 .env

复制 .env.example 到 .env，并填写你的值：

TELEGRAM_API_ID=your_api_id_here
TELEGRAM_API_HASH=your_api_hash_here
TELEGRAM_SESSION_NAME=anon
TELEGRAM_SESSION_STRING=your_session_string_here

你可以在 my.telegram.org/apps 获取你的 API 凭证。

---

🐳 使用 Docker 运行

如果你已安装 Docker 和 Docker Compose，你可以将服务器构建并运行在容器中，从而简化依赖管理。

1. 构建镜像

从项目根目录构建 Docker 镜像：

docker build -t telegram-mcp:latest .

2. 运行容器

你有两种选择：

选项 A：使用 Docker Compose（推荐用于本地使用）

此方法使用 docker-compose.yml 文件，并自动从 .env 文件中读取你的凭据。

1. 创建 .env 文件： 确保项目根目录下有一个包含 TELEGRAM_API_ID、TELEGRAM_API_HASH 和 TELEGRAM_SESSION_STRING（或 TELEGRAM_SESSION_NAME）的 .env 文件。可以使用 .env.example 作为模板。
2. 运行 Compose：

   docker compose up --build
   

   • 使用 docker compose up -d 以分离模式（后台）运行。
   • 按 Ctrl+C 停止服务器。

选项 B：使用 docker run

你可以直接运行容器，将凭据作为环境变量传递。

docker run -it --rm \
  -e TELEGRAM_API_ID="YOUR_API_ID" \
  -e TELEGRAM_API_HASH="YOUR_API_HASH" \
  -e TELEGRAM_SESSION_STRING="YOUR_SESSION_STRING" \
  telegram-mcp:latest

• 将占位符替换为你的真实凭据。
• 如果你更倾向于基于文件的会话，可以使用 -e TELEGRAM_SESSION_NAME=your_session_file_name 代替 TELEGRAM_SESSION_STRING（需要挂载卷，可参考 docker-compose.yml 中的示例）。
• -it 标志对于与服务器交互至关重要。

---

⚙️ Claude 和 Cursor 的配置

MCP 配置

编辑你的 Claude 桌面配置文件（例如 ~/Library/Application Support/Claude/claude_desktop_config.json）或 Cursor 配置文件（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py"
      ]
    }
  }
}

📝 工具示例及代码与输出

以下是几个最常用工具的示例，包括其实现和示例输出。

获取你的聊天列表

@mcp.tool()
async def get_chats(page: int = 1, page_size: int = 20) -> str:
    """
    获取分页显示的聊天列表。
    参数：
        page: 页码（从 1 开始）。
        page_size: 每页显示的聊天数量。
    """
    try:
        dialogs = await client.get_dialogs()
        start = (page - 1) * page_size
        end = start + page_size
        if start >= len(dialogs):
            return "页码超出范围。"
        chats = dialogs[start:end]
        lines = []
        for dialog in chats:
            entity = dialog.entity
            chat_id = entity.id
            title = getattr(entity, "title", None) or getattr(entity, "first_name", "未知")
            lines.append(f"聊天 ID: {chat_id}, 标题: {title}")
        return "\n".join(lines)
    except Exception as e:
        logger.exception(f"get_chats 失败（page={page}, page_size={page_size}）")
        return "发生错误（代码：GETCHATS-ERR-001）。请查看 mcp_errors.log 以获取详细信息。"

示例输出：

聊天 ID: 123456789, 标题: John Doe
聊天 ID: -100987654321, 标题: 我的项目组
聊天 ID: 111223344, 标题: Jane Smith
聊天 ID: -200123456789, 标题: 新闻频道

发送消息

@mcp.tool()
async def send_message(chat_id: int, message: str) -> str:
    """
    向指定聊天发送消息。
    参数：
        chat_id：聊天的ID。
        message：要发送的消息内容。
    """
    try:
        entity = await client.get_entity(chat_id)
        await client.send_message(entity, message)
        return "消息发送成功。"
    except Exception as e:
        logger.exception(f"send_message 失败 (chat_id={chat_id})")
        return "发生错误（代码：SENDMSG-ERR-001）。请查看 mcp_errors.log 以获取详细信息。"

示例输出：

消息发送成功。

列出内联按钮

@mcp.tool()
async def list_inline_buttons(
    chat_id: Union[int, str],
    message_id: Optional[int] = None,
    limit: int = 20,
) -> str:
    """
    查看内联键盘布局，包括按钮索引、是否支持回调以及 URL。
    """

使用示例：

list_inline_buttons(chat_id="@sample_tasks_bot")

返回结果类似如下：

消息 42 的按钮（日期：2025-01-01 12:00:00+00:00）：
[0] 文本='📋 查看任务'，支持回调
[1] 文本='ℹ️ 帮助'，支持回调
[2] 文本='🌐 访问网站'，不支持回调，URL=https://example.org

点击内联按钮

@mcp.tool()
async def press_inline_button(
    chat_id: Union[int, str],
    message_id: Optional[int] = None,
    button_text: Optional[str] = None,
    button_index: Optional[int] = None,
) -> str:
    """
    根据按钮文本或零基索引点击内联键盘按钮。
    如果未指定 message_id，服务器会搜索最近的消息以找到最新的内联键盘。
    """

使用示例：

press_inline_button(chat_id="@sample_tasks_bot", button_text="📋 查看任务")

如果需要查看可用按钮，可以先使用 list_inline_buttons——传入一个不存在的 button_text 即可快速列出选项，或者直接调用 list_inline_buttons。确定按钮文本或索引后，press_inline_button 将发送相应的回调，就像在原生 Telegram 客户端中点击按钮一样。

订阅公开频道

@mcp.tool()
async def subscribe_public_channel(channel: Union[int, str]) -> str:
    """
    通过用户名（例如：“@examplechannel”）或 ID 加入公开频道或超级群组。
    """

使用示例：

subscribe_public_channel(channel="@daily_updates_feed")

如果账号已经是参与者，该工具会报告这一情况而不是失败，因此可以在需要幂等加入的工作流中反复运行而不会出现问题。

获取聊天邀请链接

get_invite_link 函数采用了多种备用方法，非常稳健：

@mcp.tool()
async def get_invite_link(chat_id: int) -> str:
    """
    获取群组或频道的邀请链接。
    """
    try:
        entity = await client.get_entity(chat_id)
        
        # 首先尝试使用 ExportChatInviteRequest
        try:
            from telethon.tl import functions
            result = await client(functions.messages.ExportChatInviteRequest(
                peer=entity
            ))
            return result.link
        except AttributeError:
            # 如果当前版本的 Telethon 中没有此函数
            logger.warning("ExportChatInviteRequest 不可用，正在使用替代方法")
        except Exception as e1:
            # 如果失败，则记录日志并尝试其他方法
            logger.warning(f"ExportChatInviteRequest 失败：{e1}")
            
        # 替代方法：使用 client.export_chat_invite_link
        try:
            invite_link = await client.export_chat_invite_link(entity)
            return invite_link
        except Exception as e2:
            logger.warning(f"export_chat_invite_link 失败：{e2}")
            
        # 最后手段：直接获取聊天信息
        try:
            if isinstance(entity, (Chat, Channel)):
                full_chat = await client(functions.messages.GetFullChatRequest(
                    chat_id=entity.id
                ))
                if hasattr(full_chat, 'full_chat') and hasattr(full_chat.full_chat, 'invite_link'):
                    return full_chat.full_chat.invite_link or "无邀请链接可用。"
        except Exception as e3:
            logger.warning(f"GetFullChatRequest 失败：{e3}")
            
        return "无法获取此聊天的邀请链接。"
    except Exception as e:
        logger.exception(f"get_invite_link 失败 (chat_id={chat_id})")
        return f"获取邀请链接时出错：{e}"

示例输出：

https://t.me/+AbCdEfGhIjKlMnOp

通过邀请链接加入聊天

@mcp.tool()
async def join_chat_by_link(link: str) -> str:
    """
    通过邀请链接加入聊天。
    """
    try:
        # 从邀请链接中提取哈希值
        if '/' in link:
            hash_part = link.split('/')[-1]
            if hash_part.startswith('+'):
                hash_part = hash_part[1:]  # 去掉开头的 '+'
        else:
            hash_part = link
            
        # 尝试在加入前检查邀请
        try:
            # 先尝试检查邀请信息（如果不是成员通常会失败）
            invite_info = await client(functions.messages.CheckChatInviteRequest(hash=hash_part))
            if hasattr(invite_info, 'chat') and invite_info.chat:
                # 如果获取到聊天信息，说明已经是成员
                chat_title = getattr(invite_info.chat, 'title', '未知聊天')
                return f"您已经是该聊天的成员：{chat_title}"
        except Exception:
            # 如果不是成员，通常会失败，继续执行
            pass
            
        # 使用哈希值加入聊天
        result = await client(functions.messages.ImportChatInviteRequest(hash=hash_part))
        if result and hasattr(result, 'chats') and result.chats:
            chat_title = getattr(result.chats[0], 'title', '未知聊天')
            return f"成功加入聊天：{chat_title}"
        return f"已通过邀请哈希值加入聊天。"
    except Exception as e:
        err_str = str(e).lower()
        if "expired" in err_str:
            return "该邀请哈希值已过期，不再有效。"
        elif "invalid" in err_str:
            return "该邀请哈希值无效或格式错误。"
        elif "already" in err_str and "participant" in err_str:
            return "您已经是该聊天的成员。"
        logger.exception(f"join_chat_by_link 失败 (link={link})")
        return f"加入聊天时出错：{e}"

示例输出：

成功加入聊天：开发者社区

搜索公开聊天

@mcp.tool()
async def search_public_chats(query: str, limit: int = 20) -> str:
    """
    根据用户名或标题搜索公开聊天、频道或机器人。
    """
    try:
        result = await client(functions.contacts.SearchRequest(q=query, limit=limit))
        entities = [format_entity(e) for e in result.chats + result.users]
        return json.dumps(entities, indent=2)
    except Exception as e:
        return f"搜索公开聊天时出错：{e}"

示例输出：

[
  {
    "id": 123456789,
    "name": "TelegramBot",
    "type": "user",
    "username": "telegram_bot"
  },
  {
    "id": 987654321,
    "name": "Telegram News",
    "type": "user",
    "username": "telegram_news"
  }
]

获取与联系人的直接聊天

@mcp.tool()
async def get_direct_chat_by_contact(contact_query: str) -> str:
    """
    通过姓名、用户名或电话号码查找与特定联系人的直接聊天。

    参数：
        contact_query：用于搜索的姓名、用户名或电话号码。
    """
    try:
        # 使用正确的 Telethon 方法获取所有联系人
        result = await client(functions.contacts.GetContactsRequest(hash=0))
        contacts = result.users
        found_contacts = []
        for contact in contacts:
            if not contact:
                continue
            name = f"{getattr(contact, 'first_name', '')} {getattr(contact, 'last_name', '')}".strip()
            username = getattr(contact, 'username', '')
            phone = getattr(contact, 'phone', '')
            if (contact_query.lower() in name.lower() or 
                (username and contact_query.lower() in username.lower()) or 
                (phone and contact_query in phone)):
                found_contacts.append(contact)
        if not found_contacts:
            return f"未找到匹配 '{contact_query}' 的联系人。"
        # 如果找到了联系人，则查找与他们的直接聊天
        results = []
        dialogs = await client.get_dialogs()
        for contact in found_contacts:
            contact_name = f"{getattr(contact, 'first_name', '')} {getattr(contact, 'last_name', '')}".strip()
            for dialog in dialogs:
                if isinstance(dialog.entity, User) and dialog.entity.id == contact.id:
                    chat_info = f"聊天ID：{dialog.entity.id}, 联系人：{contact_name}"
                    if getattr(contact, 'username', ''):
                        chat_info += f", 用户名：@{contact.username}"
                    if dialog.unread_count:
                        chat_info += f", 未读消息：{dialog.unread_count}"
                    results.append(chat_info)
                    break
        
        if not results:
            return f"找到了匹配 '{contact_query}' 的联系人，但没有与他们相关的直接聊天。"
        
        return "\n".join(results)
    except Exception as e:
        return f"搜索直接聊天时出错：{e}"

示例输出：

聊天ID：123456789，联系人：John Smith，用户名：@johnsmith，未读消息：3条

---

🎮 使用示例

• “显示我最近的聊天”
• “向聊天 123456789 发送‘Hello world’”
• “添加电话为 +1234567890、姓名为 John Doe 的联系人”
• “创建一个名为‘Project Team’的群组，成员为 111、222、333”
• “下载聊天 123456789 中第 42 条消息的媒体文件”
• “静音聊天 123456789 的通知”
• “将用户 111 提升为聊天 123456789 的管理员”
• “搜索关于‘新闻’的公开频道”
• “加入邀请链接为 https://t.me/+AbCdEfGhIjK 的 Telegram 群组”
• “向我的收藏消息发送贴纸”
• “获取我所有的贴纸包”

您可以通过自然语言在 Claude、Cursor 或任何兼容 MCP 的客户端中使用这些工具。

---

🧠 错误处理与鲁棒性

本实现包含全面的错误处理机制：

• 会话管理：支持基于文件和基于字符串的会话
• 错误报告：详细的错误日志记录到 mcp_errors.log
• 优雅降级：关键功能提供多种回退方案
• 用户友好提示：提供清晰且可操作的错误信息，而非技术性报错
• 账号类型检测：要求机器人账号的功能会在用户账号下使用时发出警告并提示
• 邀请链接处理：能够处理各种格式的链接以及用户已加入的情况

代码设计旨在应对常见的 Telegram API 问题及限制，具有较高的鲁棒性。

---

🛠️ 贡献指南

1. Fork 此仓库：chigwell/telegram-mcp
2. 克隆您的分支：

   git clone https://github.com/<your-github-username>/telegram-mcp.git
   

3. 创建新分支：

   git checkout -b my-feature
   

4. 进行更改，并根据需要添加测试或文档。
5. 推送并打开 Pull Request 至 chigwell/telegram-mcp，并附上清晰的描述。
6. 在 PR 中标记 @chigwell 或 @l1v0n1 以供审核。

---

🔒 安全注意事项

• 切勿提交您的 .env 文件或会话字符串。
• 会话字符串赋予对您 Telegram 账号的完全访问权限，请务必妥善保管！
• 所有处理均在本地进行；除 Telegram API 外，不会将任何数据发送至其他地方。
• 请使用 .env.example 作为模板，并确保您的实际 .env 文件保持私密。
• 测试文件已在 .gitignore 中自动排除。

---

🛠️ 故障排除

• 检查日志：在您的 MCP 客户端（Claude/Cursor）和终端中查看错误信息。
• 详细错误日志可在 mcp_errors.log 中找到。
• 解释器错误？ 确保已创建并激活了 .venv 环境。
• 数据库锁定？ 请使用会话字符串认证，而非基于文件的会话。
• iCloud/Dropbox 问题？ 如果遇到奇怪的错误，请将项目移动到不含空格的本地路径。
• 更换 Telegram 密码或出现认证错误时，请重新生成会话字符串。
• 仅限机器人使用的功能 在普通用户账号下使用时会显示明确的提示信息。
• 测试脚本失败？ 请检查 .env 文件中的测试配置，确保测试账号和群组有效。

---

📄 许可证

本项目采用 Apache 2.0 许可证。

---

🙏 致谢

• Telethon
• Model Context Protocol
• Claude 和 Cursor
• chigwell/telegram-mcp（上游）

---

由 @chigwell 和 @l1v0n1 维护。欢迎提交 PR！

星标历史

贡献者

Telegram MCP 快速上手指南

Telegram MCP 是一个基于 Model Context Protocol (MCP) 的服务器，允许 Claude、Cursor 等 AI 客户端直接通过自然语言操作你的 Telegram 账号（发送消息、管理群组、读取历史纪录等）。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows (WSL2 推荐)
• Python 版本: Python 3.10 或更高版本
• 包管理器: 推荐使用 uv (极速 Python 包安装器)，也可使用 pip
• AI 客户端: 已安装支持 MCP 的客户端，如 Claude Desktop 或 Cursor
• Telegram 账号: 有效的手机号及接收验证码的能力

国内开发者提示：由于网络环境限制，连接 Telegram API 可能需要配置代理。请在运行前确保终端环境变量已设置好代理（如 export https_proxy=http://127.0.0.1:7890），或在代码中配置 Telethon 的代理参数。

安装步骤

1. 克隆项目

git clone https://github.com/chigwell/telegram-mcp.git
cd telegram-mcp

2. 安装依赖

推荐使用 uv 进行依赖管理和环境同步：

uv sync

(如果使用 pip: pip install -r requirements.txt)

3. 获取 Telegram API 凭证

1. 访问 my.telegram.org/apps 并登录。
2. 创建一个新的 Application。
3. 记录下 API ID 和 API Hash。

4. 生成会话字符串 (Session String)

运行官方提供的脚本进行身份验证，这将生成一个会话字符串，避免每次启动都需输入验证码：

uv run session_string_generator.py

按照终端提示输入手机号和收到的验证码。成功后，脚本会自动更新 .env 文件或输出会话字符串。

5. 配置环境变量

复制示例配置文件并填入你的凭证：

cp .env.example .env

编辑 .env 文件，填入以下内容：

TELEGRAM_API_ID=你的 API_ID
TELEGRAM_API_HASH=你的 API_Hash
TELEGRAM_SESSION_NAME=anon
TELEGRAM_SESSION_STRING=上一步生成的会话字符串

基本使用

方式一：直接运行服务器

在终端中启动 MCP 服务器：

uv run main.py

此时服务器将在标准输出运行，等待 MCP 客户端连接。

方式二：在 Claude Desktop 中集成

1. 打开 Claude Desktop 的配置文件 (claude_desktop_config.json)。
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
2. 添加 telegram-mcp 配置项：

{
  "mcpServers": {
    "telegram": {
      "command": "uv",
      "args": ["--directory", "/绝对路径/到/telegram-mcp", "run", "main.py"],
      "env": {
        "TELEGRAM_API_ID": "你的 API_ID",
        "TELEGRAM_API_HASH": "你的 API_Hash",
        "TELEGRAM_SESSION_STRING": "你的会话字符串"
      }
    }
  }
}

注意：请将 /绝对路径/到/telegram-mcp 替换为你本地的实际项目路径。

3. 重启 Claude Desktop。

使用示例

连接成功后，你可以在对话框中直接使用自然语言指令，例如：

• 读取消息: "帮我列出最近 'Python 交流群' 里的 10 条消息。"
• 发送消息: "给 @username 发送一条消息：'你好，这是测试内容'。"
• 管理群组: "查看我管理的群组列表，并把用户 @bad_user 从 '测试组' 中移除。"
• 搜索内容: "在所有聊天中搜索包含 '会议记录' 的消息。"

安全提示: 涉及文件读写（如发送图片、下载媒体）的功能默认是禁用的，需要在启动命令中显式指定允许的根目录路径（allowed roots）才能使用。