Skip to main content
Glama
Sign In
deenesjakoruzh
telegram-mcp

telegram-mcp

by Shaan-alpha
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Telegram MCP Server

一个本地 Model Context Protocol 服务器，让 AI 代理（Claude Code、Claude Desktop 或任何 MCP 客户端）通过 Telegram 的 MTProto API 对你自己的 Telegram 账户进行受控访问：列出聊天、读取历史记录、搜索和发送消息。

使用 Python + Telethon 构建。完全在你的机器上运行；你的登录会话永远不会离开它。

Python MCP License

为什么

Telegram 的机器人 API 无法看到你现有的聊天；机器人是一个独立的身份，只能接收明确发送给它的消息。要让代理处理你的真实对话，你需要MTProto 客户端 API，并以你的用户账户身份进行认证。本项目将其封装在一个小巧、专注的 MCP 服务器中，使任何支持 MCP 的代理都能读取和操作你的 Telegram；无需你每次都编写胶水代码。

Related MCP server: tdlib-mcp-server

整体架构

Telegram 机器人是一个独立的身份，只能看到发送给它的消息。为了让代理处理你的对话，服务器通过 MTProto 以你的用户账户身份进行认证，这就是会话字符串如此重要的原因。

flowchart LR
    AGENT["<b>MCP client</b><br/>Claude Code · Claude Desktop<br/>or any MCP-capable agent"]

    subgraph LOCAL ["Your machine — nothing leaves it but Telegram traffic"]
        direction TB
        SRV["<b>server.py</b> · FastMCP stdio server<br/>connects lazily on first tool call<br/>verifies the session is authorized"]
        TOOLS["<b>6 tools</b><br/>get_me · list_chats · get_history<br/>search_messages · search_all · send_message"]
        ENV[("<b>.env</b> · git-ignored<br/>api_id · api_hash<br/><b>SESSION_STRING</b><br/><i>equivalent to being logged in as you</i>")]
        LOGIN["<b>login.py</b> · run once<br/>phone + code + 2FA → StringSession"]
        SRV --> TOOLS
        LOGIN -->|"writes"| ENV
        ENV -->|"reads"| SRV
    end

    subgraph TL ["Telethon → MTProto"]
        direction TB
        M1["iter_dialogs"]
        M2["iter_messages"]
        M3["SearchGlobalRequest"]
        M4["send_message"]
    end

    TG[("<b>Telegram</b><br/>your real account,<br/>your existing chats")]
    BOT(["Bot API<br/><i>cannot see your chats —<br/>this is why MTProto</i>"])

    AGENT <-->|"MCP over stdio"| SRV
    TOOLS --> M1
    TOOLS --> M2
    TOOLS --> M3
    TOOLS --> M4
    TL <--> TG
    BOT -.->|"✗"| TG

    classDef secret fill:#7f1d1d,stroke:#f87171,stroke-width:2px,color:#fee2e2
    classDef no fill:#0f172a,stroke:#475569,stroke-width:1.5px,color:#94a3b8
    classDef core fill:#312e81,stroke:#818cf8,stroke-width:2px,color:#e2e8f0
    class ENV secret
    class BOT no
    class SRV,TOOLS core

结果以纯 JSON 可序列化的字典形式返回，因此代理从结构化数据而非抓取的文本中进行总结。

功能特性

  • 6 个工具，涵盖常见的读写操作（见下文）

  • 仅本地 —— 凭据和会话存放在被 git 忽略的 .env 中；除 Telegram 外不会发送到任何地方

  • 标准 MCP stdio 服务器 —— 适用于 Claude Code、Claude Desktop 或任何 MCP 客户端

  • 一次性登录 —— 交互式脚本存储可复用的会话字符串；无需每次运行都重新认证

  • 小巧易读 —— 约 150 行 Python 代码，易于审计和扩展

工具

工具

描述

get_me()

返回已连接的账户（健全性检查）

list_chats(limit=20)

你最近的对话

get_history(chat, limit=30)

某个聊天中的最近消息

search_messages(chat, query, limit=30)

在单个聊天中搜索

search_all(query, limit=30)

一次搜索所有聊天

send_message(chat, text)

以你的身份发送消息

chat 接受用户名（@name）、数字 ID、电话号码、t.me 链接或聊天的显示名称。

快速开始

1. 安装

git clone https://github.com/<you>/telegram-mcp.git
cd telegram-mcp
python -m venv .venv

# Windows
.venv\Scripts\pip install -r requirements.txt
# macOS / Linux
.venv/bin/pip install -r requirements.txt

2. 获取 API 凭据

前往 my.telegram.org → API 开发工具 → 创建一个应用 → 复制 api_id 和 api_hash。

3. 登录（一次性）

# Windows
.venv\Scripts\python login.py
# macOS / Linux
.venv/bin/python login.py

输入你的 api_id/api_hash、电话号码（含国家代码）以及 Telegram 发送给你的登录验证码（如果设置了 2FA 密码，还需输入）。这会将可复用的会话写入 .env。

4. 注册到你的 MCP 客户端

Claude Code：

claude mcp add telegram --scope user -- "/abs/path/.venv/bin/python" "/abs/path/server.py"

Claude Desktop；添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "telegram": {
      "command": "/abs/path/.venv/bin/python",
      "args": ["/abs/path/server.py"]
    }
  }
}

重启你的客户端，telegram 工具即可使用。

示例

你： 在我所有 Telegram 聊天中搜索"invoice"，并总结未完成的事项。

代理调用 search_all("invoice")，返回：

[
  {
    "id": 84213,
    "date": "2026-07-02T09:14:00+00:00",
    "chat": "Acme Billing",
    "from": "Acme Billing",
    "text": "Invoice #204 is due on the 10th."
  }
]

……然后代理据此进行总结。

工作原理

login.py 通过 Telethon 进行一次认证，并将 StringSession 保存到 .env。server.py 构建一个 FastMCP stdio 服务器，在首次工具调用时惰性连接，验证会话已授权，并将每个工具映射到 Telethon 调用（iter_dialogs、iter_messages、SearchGlobalRequest、send_message）。结果以纯 JSON 可序列化的字典形式返回。

安全性

  • 保持 .env 私密。 SESSION_STRING 等同于以你的身份登录。它已被 git 忽略，切勿提交它。

  • 一切都在本地运行；服务器只与 Telegram 的服务器通信。

  • 自动化用户账户是 Telegram 服务条款的灰色地带。读取你自己的账户通常没问题；保持发送节奏接近人类，避免批量/垃圾活动，以免触发账户限制。

局限性

  • 尚无自动化测试套件；已针对真实账户进行手动验证。

  • search_messages 搜索单个聊天；全局搜索请使用 search_all。

  • 显示名称解析会回退到扫描你的对话列表，因此精确的用户名/ID 更快、更可靠。

许可证

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale
ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Related MCP Servers

  • telegram-mcp

    VovaVindar
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to read, send, and organize Telegram messages and chats. Supports tools for listing chats, fetching messages, sending/reply, archiving, muting, and folder management.
    1
    MIT

  • tdlib-mcp-server

    Crocodile-beep
    F
    license
    Not graded
    quality
    D
    maintenance
    Connects AI agents to Telegram via the official TDLib library, enabling tools like getting user info, listing dialogs, and searching messages.
    -

  • telegram-mcp

    naim30
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to control a real Telegram user account via MTProto, allowing message sending, chat reading/searching, and message management through MCP tools.
    40 npm
    -

  • Telegram MCP Server

    Muhammadyunusxon
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI assistants to control a personal Telegram account for sending/reading messages, media, group management, and more via the MTProto API.
    MIT

Appeared in Searches