local-only server

The server can only run on the client’s local machine because it depends on local resources.

Integrations

Allows Claude to access a Telegram account to read chats, view messages, send messages, mark messages as read, and retrieve conversation context to formulate natural-sounding replies.

Telegram MCP 服务器

这是一个简单的 MCP 服务器，可让 Claude 访问您的 Telegram 帐户来阅读和发送消息。

功能

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

设置

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

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

第 2 步：设置 Python 环境

安装所需的软件包：

# Clone the repository within your desired directory (if you haven't already)
git clone https://github.com/alexandertsai/mcp-telegram
cd mcp-telegram

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

# Set up virtual environment
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=phone number with country code and no spaces
export TELEGRAM_API_ID=api_id
export TELEGRAM_API_HASH=api_hash

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

对于 Windows (Powershell)：

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

$env:TELEGRAM_PHONE="phone number with country code and no spaces"
$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 桌面

编辑您的 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 为“/”），您可能需要将路径中的反斜杠替换为正斜杠。

非常重要：

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

步骤 6（可选）：

如果您希望聊天机器人做出响应并发出与您相似的声音，请随意在src/mcp_telegram中配置convostyle.txt 。

就是这样！

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

显示您最近的 Telegram 聊天
阅读特定聊天的消息
将某些消息标记为“已读”
以自然的声音向您的联系人或群组发送消息

向 Claude 询问提示时，务必包含“Telegram”一词，否则它可能无法理解。例如，“Claude，我还有未读的电报消息吗？”

令人厌烦的故障排除

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

ls -la ~/.mcp_telegram_*

然后使用以下命令终止会话文件（只需复制并粘贴前面带有 rm 的文件路径）

rm /Users/username/.mcp_telegram_numberininternationalformat*

再次尝试步骤 3。

This server cannot be installed

-

security - not tested

A

license - permissive license

-

quality - not tested

一个简单的 MCP 服务器，允许 Claude 访问您的 Telegram 帐户，代表您阅读和发送消息。

Telegram MCP Server