Skip to main content
Glama
Anonymouse8882

Telegram MCP

by Anonymouse8882
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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 .

Related MCP server: tgmcp

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

Copyright (c) 2026 Anonymouse8882

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

Licensed under GPL v3.

Install Server
F
license - not found
B
quality
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

  • tgmcp

    OEvortex
    A
    license
    -
    quality
    B
    maintenance
    Enables AI agents to interact with Telegram accounts through MCP, supporting messaging, contacts, groups, media, and admin functions.
    Last updated
    4
    Apache 2.0

  • Telegram MCP Server

    OrrBin
    A
    license
    -
    quality
    D
    maintenance
    Enables full access to your personal Telegram account via MCP, allowing reading, sending, and searching messages, managing chats, and retrieving user information through natural language commands.
    Last updated
    36
    2
    MIT

View all related MCP servers

Related MCP Connectors

  • telegram-mcp

    Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.

  • mcp

    MemberPass MCP — manage projects, plans, members, payments, and analytics for Telegram creators.

  • fast-mcp-telegram

    Multi-tenant Telegram gateway for AI agents — HTTP+stdio, 8 tools, MTProto User API

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Anonymouse8882/TelegamMCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server