Telegram MCP 服务器

这是一个简单的 MCP 服务器，允许 Claude 访问您的 Telegram 帐户以读取和发送消息。

功能

1. get_chats: 获取您的 Telegram 聊天列表
2. send_message: 向聊天发送消息
3. get_message: 从聊天中获取消息并打印未读消息
4. mark_messages_read: 将消息标记为已读
5. get_conversation_context: 获取过去 20 条消息并读取 convostyle.txt 以确定合适的回复

设置

步骤 1：获取您的 Telegram API 凭据

1. 前往 https://my.telegram.org/apps
2. 登录并创建一个应用程序（或使用现有的应用程序）
3. 记下您的 API ID 和 API Hash

步骤 2：设置 Python 环境

安装所需的软件包：

# 在您想要的目录中克隆存储库（如果尚未克隆）
git clone https://github.com/alexandertsai/mcp-telegram
cd mcp-telegram

设置虚拟环境。如果适用，请改用 pip3。

# 设置虚拟环境
pip install uv mcp
uv venv
source .venv/bin/activate
# .venv\Scripts\activate for windows
uv add "mcp[cli]" telethon python-dotenv nest_asyncio

步骤 3：添加 ID

对于 Mac (bash)：

在虚拟环境中，运行以下命令：

export TELEGRAM_PHONE=带国家代码且无空格的电话号码
export TELEGRAM_API_ID=api_id
export TELEGRAM_API_HASH=api_hash

使用终端中的 printenv 检查它们是否已导出。

对于 Windows (Powershell)：

在虚拟环境中，运行以下命令。 确保包含引号，否则 powershell 可能会遇到问题：

$env:TELEGRAM_PHONE="带国家代码且无空格的电话号码"
$env:TELEGRAM_API_ID="api_id"
$env:TELEGRAM_API_HASH="api_hash"

使用 powershell 中的 gci env: 检查它们是否已导出。

步骤 4：运行身份验证

运行此命令进行身份验证。 如果您启用了 2FA，则在输入密码时，您不会在终端中看到任何文本出现。 这是正常的！ 尽量不要在 2FA 期间输入错误 - 如果您这样做，它会使您重新启动整个过程... 根据您安装的版本使用 python 或 python3：

cd src/mcp_telegram
python3 telethon_auth.py

系统会要求您提供：

• 您的电话号码（采用国际格式，带 +）（不要留下任何空格）
• Telegram 发送到您帐户的代码
• 您的 2FA 密码（如果已启用）

这会在您的主目录中创建一个会话文件，因此您无需再次进行身份验证。

步骤 5：添加到 Claude Desktop

编辑您的 Claude Desktop 配置：

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

或者，转到设置，单击“开发者”，然后单击“编辑配置”。 确保已启用开发者模式。

将此添加到您的配置中（替换为您实际的凭据）：

"mcpServers": {
      "telegram": {
      "command": "/your/path/to/python3",
      "args": ["/full/path/to/mcp-telegram/main.py"],
      "env": {
          "TELEGRAM_API_ID": "your_api_id_here",
          "TELEGRAM_API_HASH": "your_api_hash_here",
          "TELEGRAM_PHONE": "+65945678900"
          }
      }
  }

main.py: 要获取完整路径，请转到您的 IDE 或桌面，找到该文件，右键单击它，然后单击“复制路径”。

python: 在您的终端中运行 where.exe python (Windows) 或 where python (Mac) 以获取完整路径（如果需要，请替换为 python3）。 如果在 Windows 上，您可能需要将路径中的反斜杠替换为正斜杠，因为 JSON 格式（ctrl+f "\", 全部替换 (ctrl + h) 为 "/"）。

非常重要：

1. 使用 Python 和 main.py 脚本的完整绝对路径
2. 将 API 凭据替换为步骤 1 中的实际值
3. 以国际格式设置您的电话号码

步骤 6（可选）：

如果您希望聊天机器人像您一样回复和发声，请随意配置 src/mcp_telegram 中的 convostyle.txt。

就是这样！

重新启动 Claude Desktop（退出并重新打开），现在您可以要求 Claude：

• 显示您最近的 Telegram 聊天
• 阅读来自特定聊天的消息
• 将某些消息标记为“已读”
• 向您的联系人或群组发送消息，同时听起来很自然

在向 Claude 提出提示时，请务必包含“Telegram”一词，否则它可能无法理解。 例如，“Claude 我有任何未读的 Telegram 消息吗？”

令人讨厌的故障排除

在虚拟环境中，尝试运行：

ls -la ~/.mcp_telegram_*

然后终止您的会话文件（只需复制并粘贴文件路径，并在前面加上 rm）

rm /Users/username/.mcp_telegram_numberininternationalformat*

再次尝试步骤 3。