Telegram MCP Server

用于通过 Telegram Bot API 与 Telegram 交互的 MCP 服务器。该服务器为 LLM 客户端提供一组工具，用于发送消息、读取最近可用的消息以及获取聊天信息。

功能特性

服务器提供三个 MCP 工具：

• send_message — 向指定的 Telegram 聊天发送文本消息。

• get_recent_messages — 获取指定聊天中最近可用的消息。

• get_chat_info — 返回 Telegram 聊天的基本信息。

服务器使用 stdio 传输，因此可以连接到 MCP Inspector 和其他 MCP 客户端，而无需单独的 HTTP 服务器。

Related MCP server: agent-telegram-mcp

架构

MCP client / MCP Inspector
            │
            │ MCP over stdio
            ▼
      src/server.py
            │
            ▼
   src/telegram_client.py
            │
            │ HTTPS
            ▼
    Telegram Bot API

server.py 负责 MCP 接口和工具注册。

telegram_client.py 封装了与 Telegram Bot API 的 HTTP 交互。

config.py 从环境变量加载令牌。

技术栈

• Python 3.10+

• MCP Python SDK 2.x

• Telegram Bot API

• httpx

• python-dotenv

项目结构

telegram-mcp/
├── src/
│   ├── __init__.py
│   ├── config.py
│   ├── telegram_client.py
│   └── server.py
├── .env.example
├── .gitignore
├── requirements.txt
└── README.md

要求

• Python 3.10 或更高版本

• 通过 @BotFather 创建的 Telegram 机器人

• Node.js 和 npx — 仅当通过 mcp dev 使用 MCP Inspector 时需要

安装

克隆仓库并进入其目录：

git clone <repository-url>
cd telegram-mcp

创建虚拟环境：

python3 -m venv .venv
source .venv/bin/activate

安装依赖：

pip install -r requirements.txt

配置 Telegram 机器人

1. 打开 Telegram 并找到 @BotFather。

2. 执行 /newbot。

3. 创建机器人并获取 Bot API 令牌。

4. 不要将令牌添加到源代码或 Git。

创建 .env 文件：

cp .env.example .env

指定令牌：

TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here

.env 已添加到 .gitignore。

准备聊天

私聊

1. 打开已创建的机器人。

2. 点击 Start 或向其发送消息。

3. 为了测试 get_recent_messages，请发送几条文本消息。

群组

1. 创建一个测试群组。

2. 将机器人添加到群组中。

3. 如果机器人需要查看群组的普通消息，请通过 @BotFather 关闭其隐私模式（/setprivacy → Disable）。

4. 向群组发送几条消息。

为了获取 chat_id，可以在机器人从目标聊天收到消息后，先调用 get_chat_info 或 get_recent_messages。

运行

从项目根目录：

python src/server.py

服务器通过 stdio 运行并等待 MCP 连接。因此，启动后终端没有常规输出属于正常现象。

可以使用 MCP CLI 进行开发和测试：

mcp dev src/server.py

该命令启动服务器和 MCP Inspector。Inspector 使用 npx，因此 Node.js 必须在 PATH 中可用。

MCP 工具

send_message

向 Telegram 发送文本消息。

参数：

chat_id: string — ID чата
text: string — текст сообщения

示例：

chat_id: 123456789
text: Привет! Сообщение отправлено через MCP.

服务器在响应中返回发送确认和 message_id。

get_recent_messages

获取指定聊天的最近可用消息。

参数：

chat_id: string — ID чата
limit: integer — количество сообщений, по умолчанию 10

limit 限制在 1 到 100 的范围内。

示例：

chat_id: 123456789
limit: 10

结果包含每条可用消息的发送者和文本。

get_chat_info

获取聊天的基本信息。

参数：

chat_id: string — ID чата

响应中显示可用字段，包括 ID、类型、名称、username、名字和姓氏。

消息获取的工作原理

Telegram Bot API 不向机器人提供单独的方法来读取任意聊天历史。为了获取传入消息，服务器使用 getUpdates。

get_recent_messages 请求最多 100 条最近可用的 updates，然后按 chat_id 过滤。因此，该工具处理的是 Telegram 通过 updates 队列提供给机器人的消息，而不是完整的聊天历史。

这意味着该工具不能替代可以访问完整聊天记录的 Telegram 客户端。要测试，只需在将机器人添加到聊天后发送消息，然后调用 get_recent_messages 即可。

重要：getUpdates 不能与活动的 webhook 同时使用。如果机器人配置了 webhook，请先删除它，以便通过 getUpdates 的 long polling 能够接收 updates。

示例场景

1. 启动 MCP Inspector。

2. 连接 src/server.py。

3. 确保以下工具可用：

   • send_message

   • get_recent_messages

   • get_chat_info

4. 调用 get_chat_info 以验证与聊天的连接。

5. 调用 send_message 并确认消息已出现在 Telegram 中。

6. 在 Telegram 中发送几条消息。

7. 调用 get_recent_messages 并检查返回的消息列表。

安全性

Telegram Bot API 令牌仅通过环境变量 TELEGRAM_BOT_TOKEN 传递。

真实的 .env 文件不应提交到 Git。仓库中只保留不包含实际令牌的 .env.example。

限制

• 机器人无法通过 Bot API 访问完整的 Telegram 聊天历史。

• get_recent_messages 处理可用的 bot updates。

• 在群组中，机器人收到的消息集合取决于 Telegram 的隐私设置。

• getUpdates 和 webhook 是互斥的获取 updates 的方式。