Telegram MCP 服务器

将 Claude 连接到您的 Telegram 账户以读取和发送消息。

功能

可用工具

1. get_chats - 列出您的 Telegram 对话

   • 返回分页列表，包含对话名称、ID 和未读消息数量
   • 对于第一页，只需提供页面编号
   • 对于后续页面，请使用上一个响应中的分页参数

2. get_messages - 从特定对话中读取消息

   • 获取分页的消息历史记录
   • 自动标记消息为已读

3. mark_messages_read - 将对话中的所有未读消息标记为已读

4. send_message - 向任何对话发送消息

   • 支持回复特定消息

5. get_conversation_context - 分析对话风格以生成自然回应

   • 从 convostyle.txt 文件中读取您的对话风格指南
   • 帮助 Claude 匹配您的文本模式

安装指南

第一步：获取 Telegram API 凭证

1. 访问 https://my.telegram.org/apps
2. 登录并创建一个应用程序
3. 保存您的 API ID 和 API Hash

第二步：安装

# 克隆仓库
git clone https://github.com/alexandertsai/mcp-telegram
cd mcp-telegram

# 设置 Python 环境
pip install uv
uv venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate
uv sync

第三步：配置

# 复制示例文件
cp .env.example .env

# 编辑 .env 并添加您的 API 凭证：
# TELEGRAM_API_ID=your_api_id_here
# TELEGRAM_API_HASH=your_api_hash_here

第四步：认证

cd src/mcp_telegram
python telethon_auth.py

按照提示操作：

• 输入您的电话号码（包括国家代码，例如 +1234567890）
• 输入发送到您 Telegram 的验证码
• 如果有，请输入您的 2FA 密码

第五步：添加到 Claude Desktop

找到您的 Claude Desktop 配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

添加以下配置：

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/python",
      "args": ["/path/to/mcp-telegram/src/mcp_telegram/main.py"]
    }
  }
}

查找路径的方法：

• Python：运行 which python（Mac）或 where.exe python（Windows）
• main.py：右键点击文件并选择“复制路径”

重启 Claude Desktop。

使用方法

设置完成后，您可以要求 Claude：

• “检查我的 Telegram 消息”
• “给 [联系人姓名] 发送一条消息”
• “我有哪些未读对话？”
• “回复来自 [联系人姓名] 的最后一条消息”

样式指南（可选）

创建 src/mcp_telegram/convostyle.txt 来帮助 Claude 匹配您的文本风格：

我和朋友随意地发短信，与工作联系人则正式些。
我很少使用表情符号，并且更喜欢短消息。

故障排除

认证问题

如果认证失败：

1. 检查 .env 文件中的 API 凭证
2. 删除 .env 中的 TELEGRAM_SESSION_STRING 行
3. 再次运行 python telethon_auth.py

常见错误

• "请设置 TELEGRAM_API_ID 和 TELEGRAM_API_HASH"：缺少 .env 文件或凭证
• "会话字符串无效或已过期"：重新运行认证
• 2FA 密码不显示：这是正常的 - 继续输入

要求

• Python 3.10+
• Claude Desktop
• Telegram 账户

许可证

Apache 2.0