F
licenseNot graded
qualityD
maintenanceConnects AI agents to Telegram via the official TDLib library, enabling tools like getting user info, listing dialogs, and searching messages.
-
telegram-mcp-server
by Steph-ux
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 凭据
使用你的手机号码登录
创建一个应用 → 获取 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: telegram-mcp
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-mcp3. 工具目录（9 个工具，8 个操作）
tg_session — 会话管理
操作 | 必需参数 | 描述 |
|
| 认证（支持两步验证） |
| — | 检查登录状态 |
| — | 删除会话 |
tg_message — 发送、转发、删除、回复
操作 | 必需参数 | 描述 |
|
| 发送消息 |
|
| 转发消息 |
|
| 删除消息 |
|
| 回复消息 |
tg_chat — 聊天操作
操作 | 必需参数 | 描述 |
| — | 列出最近的聊天 |
|
| 获取聊天信息 |
|
| 列出聊天成员 |
|
| 离开聊天 |
tg_search — 搜索
操作 | 必需参数 | 描述 |
|
| 搜索消息（可选在 |
|
| 搜索联系人/用户 |
|
| 搜索频道 |
tg_history — 聊天历史
操作 | 必需参数 | 描述 |
|
| 获取消息历史 |
|
| 仅获取媒体历史 |
|
| 仅获取文件历史 |
tg_user — 用户操作
操作 | 必需参数 | 描述 |
| — | 获取你自己的信息 |
|
| 获取用户信息 |
|
| 屏蔽用户 |
|
| 解除屏蔽用户 |
tg_media — 发送媒体
操作 | 必需参数 | 描述 |
|
| 发送照片 |
|
| 发送视频 |
|
| 发送文档 |
|
| 发送语音消息 |
tg_channel — 频道管理
操作 | 必需参数 | 描述 |
|
| 创建超级群组/频道 |
|
| 加入频道 |
|
| 离开频道 |
|
| 获取频道信息 |
tg_draft — 草稿消息
操作 | 必需参数 | 描述 |
|
| 保存草稿 |
| — | 列出所有草稿 |
|
| 删除草稿 |
4. 环境变量
变量 | 默认值 | 描述 |
|
| Telegram API ID（来自 my.telegram.org） |
|
| Telegram API Hash |
|
| 会话文件位置 |
5. 安全
速率限制：发送操作限制为每分钟 5 次。读取操作无限制。
FloodWaitError 处理：等待所需时间（上限 5 分钟）。
会话文件：仅本地存储，绝不提交到 git。
两步验证（2FA）支持：支持启用两步验证的账户。
6. MCP 资源
tg://version— 服务器版本tg://session— 登录状态
许可证
MIT
This server cannot be deployed
Maintenance
ActivitySlowing
ResponsivenessNo issues
Related MCP Connectors
Telegram: FASTEST real time Telegram API. Retrieve channel's info and messages in milliseconds..
Multi-tenant Telegram gateway for AI agents — HTTP+stdio, 8 tools, MTProto User API
I use your linked Telegram MTProto session (Integrations → Telegram) to list groups, members, and s…
Telegram CRM: manage contacts, conversations, tickets, campaigns and analytics.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Telegram Bot API for sending messages, photos, editing messages, answering callbacks, and fetching updates.MIT
- AlicenseNot gradedqualityBmaintenanceEnables sending Telegram messages, photos, and documents, and retrieving bot information through the Telegram Bot API.31 npm1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to interact with a user's Telegram account: list chats, read history, search, and send messages through Telegram's MTProto API.1MIT