Skip to main content
Glama
deenesjakoruzh
Steph-ux

telegram-mcp-server

by Steph-ux
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

telegram-mcp-server

一个基于 Telethon 的 Telegram MCP 服务器 —— 持久化客户端、防洪水机制、9 个分组的工具。

代码中零 API 密钥。 会话文件存储在本地。支持用户账户（两步验证）和机器人。

1. 安装

git clone <this-repo> telegram-mcp-server
cd telegram-mcp-server

python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

pip install -e .

获取你的 API 凭据

  1. 前往 my.telegram.org

  2. 使用你的手机号码登录

  3. 创建一个应用 → 获取 API ID 和 API Hash

一次性认证

# User account (with 2FA support)
export TG_API_ID=12345
export TG_API_HASH="your_hash_here"
telegram-mcp-server --auth --phone +33612345678

# Or via MCP tool: tg_session(action="auth", api_id=12345, api_hash="...", phone="+33612345678")

Related MCP server: tdlib-mcp-server

2. 在你的 MCP 客户端中注册

Claude Desktop / OpenCode

{
  "mcpServers": {
    "telegram": {
      "command": "telegram-mcp-server",
      "env": {
        "TG_API_ID": "12345",
        "TG_API_HASH": "your_hash_here"
      }
    }
  }
}

如果不在 PATH 中：

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "telegram_mcp_server"],
      "env": {
        "TG_API_ID": "12345",
        "TG_API_HASH": "your_hash_here"
      }
    }
  }
}

Docker

docker build -t telegram-mcp .
docker run -i --rm \
  -v ~/.telegram-mcp/sessions:/root/.telegram-mcp/sessions \
  -e TG_API_ID=12345 \
  -e TG_API_HASH="your_hash" \
  telegram-mcp

3. 工具目录（9 个工具，8 个操作）

tg_session — 会话管理

操作

必需参数

描述

auth

api_id、api_hash、phone 或 bot_token

认证（支持两步验证）

check

—

检查登录状态

logout

—

删除会话

tg_message — 发送、转发、删除、回复

操作

必需参数

描述

send

target、text

发送消息

forward

target、message_id、to_target

转发消息

delete

target、message_id

删除消息

reply

target、message_id、text

回复消息

tg_chat — 聊天操作

操作

必需参数

描述

list

—

列出最近的聊天

info

target

获取聊天信息

members

target

列出聊天成员

leave

target

离开聊天

tg_search — 搜索

操作

必需参数

描述

messages

query

搜索消息（可选在 target 中）

users

query

搜索联系人/用户

channels

query

搜索频道

tg_history — 聊天历史

操作

必需参数

描述

messages

target

获取消息历史

media

target

仅获取媒体历史

files

target

仅获取文件历史

tg_user — 用户操作

操作

必需参数

描述

me

—

获取你自己的信息

info

target

获取用户信息

block

target

屏蔽用户

unblock

target

解除屏蔽用户

tg_media — 发送媒体

操作

必需参数

描述

send_photo

target、file_path

发送照片

send_video

target、file_path

发送视频

send_file

target、file_path

发送文档

send_voice

target、file_path

发送语音消息

tg_channel — 频道管理

操作

必需参数

描述

create

title

创建超级群组/频道

join

target

加入频道

leave

target

离开频道

info

target

获取频道信息

tg_draft — 草稿消息

操作

必需参数

描述

save

target、text

保存草稿

list

—

列出所有草稿

delete

target

删除草稿

4. 环境变量

变量

默认值

描述

TG_API_ID

0

Telegram API ID（来自 my.telegram.org）

TG_API_HASH

""

Telegram API Hash

TG_SESSION_DIR

~/.telegram-mcp/sessions

会话文件位置

5. 安全

  • 速率限制：发送操作限制为每分钟 5 次。读取操作无限制。

  • FloodWaitError 处理：等待所需时间（上限 5 分钟）。

  • 会话文件：仅本地存储，绝不提交到 git。

  • 两步验证（2FA）支持：支持启用两步验证的账户。

6. MCP 资源

  • tg://version — 服务器版本

  • tg://session — 登录状态

许可证

MIT

This server cannot be installed

F
license - not found
Not graded
quality - not tested
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.

Related MCP Servers

  • tdlib-mcp-server

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

  • telegram-mcp

    chenzhaoxuan0
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables interaction with Telegram Bot API for sending messages, photos, editing messages, answering callbacks, and fetching updates.
    MIT

View all related MCP servers

Related MCP Connectors

  • fast-mcp-telegram

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

  • telegram-mcp

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

  • tgden — Telegram catalog & search

    Search 1.2M+ Telegram channels, 245k+ chats, 160k+ bots — no account, no key, no install.

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/Steph-ux/telegram-mcp-server'

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