Telegram机器人消息管理服务

电报机器人MCP服务器

一种模型上下文协议（MCP）服务器，使AI助手能够在Telegram频道中发布、编辑、搜索和管理消息。

特性

• 发布短信：通过格式支持（Markdown/HTML）将新短信发布到Telegram频道
• 发布照片：将带有可选字幕的照片发布到Telegram频道
• 编辑短信：修改频道中现有的纯文本消息
• 编辑照片标题：更新现有照片信息的标题
• 删除消息：从频道中删除消息
• 搜索邮件：搜索缓存的邮件（本地缓存）
• 通道信息：检索频道元数据和统计信息

快速参考

重要提示： 您不能使用 edit_message 在照片信息或 edit_message_caption 关于短信！

安装

先决条件

1. Python 3.10+ 是必需的

2. 创建Telegram Bot:

   • 打开Telegram并搜索 @植物学家
   • 发送 /newbot 并遵循指示
   • 复制机器人令牌（格式： 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)

3. 将Bot添加到您的频道:

   • 创建Telegram频道或使用现有频道
   • 将您的机器人添加为频道管理员
   • 授予机器人权限：
     • 发布消息
     • 编辑他人的消息
     • 删除他人的消息

4. 获取频道ID:

   • 对于公共频道，请使用用户名格式： @channelname
   • 对于私人频道，您需要数字聊天ID（例如。， -1001234567890)
   • 您可以通过以下方式获得：
     • 将机器人添加到频道
     • 向频道发送消息
     • 使用以下方式检查更新： https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates

从源代码安装

# Clone the repository
git clone https://github.com/aggeentik/telegram-bot-mcp.git
cd telegram-bot-mcp

# Install with pip
pip install -e .

# Or install with uv (recommended)
uv pip install -e .

为了发展

# Install with dev dependencies
pip install -e ".[dev]"

# Or with uv
uv pip install -e ".[dev]"

配置

环境变量

将您的Telegram机器人令牌设置为环境变量：

export TELEGRAM_BOT_TOKEN="your-bot-token-here"

或者将其添加到您的 .env 文件：

TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

Claude桌面集成

将此添加到您的Claude Desktop配置文件中：

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "telegram-bot": {
      "command": "python",
      "args": ["-m", "telegram_bot"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-bot-token-here"
      }
    }
  }
}

或者，如果通过紫外线安装：

{
  "mcpServers": {
    "telegram-bot": {
      "command": "uvx",
      "args": ["telegram-bot-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-bot-token-here"
      }
    }
  }
}

用法

配置后，服务器将可用于您的MCP客户端（如Claude Desktop）。您可以要求AI助手：

• “向@mychannel发布一条消息，说‘人工智能你好！’”
• “将照片从/path/to/image.jpg发布到@mychannel，并添加标题‘看看这个！’”
• “在@mychannel中编辑消息12345，使其显示‘已更新消息’”
• “在@mychannel中搜索包含‘重要’的邮件”
• “从@mychannel删除邮件12345”
• “获取有关@mychannel的信息”

可用工具

publish_message

向Telegram频道发布新消息。

参数：

• channel_id （str，必填）：频道用户名(@mychannel)或聊天ID
• text （str，必填）：要发布的消息文本
• parse_mode （str，可选）：文本格式- "Markdown", "HTML"，或 "None"默认值： "Markdown"
• disable_web_page_preview （bool，可选）：禁用链接预览。违约： False
• disable_notification （bool，可选）：静默发送。违约： False

退货：

{
  "message_id": 12345,
  "chat_id": -1001234567890,
  "date": "2024-01-15T10:30:00",
  "text": "Your message text",
  "link": "https://t.me/mychannel/12345"
}

publish_photo

将照片发布到带有可选标题的Telegram频道。

参数：

• channel_id （str，必填）：频道用户名(@mychannel)或聊天ID
• photo （str，必填）：要发送的照片（文件路径、URL或file_id）
• caption （str，可选）：带有Markdown/HTML格式的标题文本。最多1024个字符
• parse_mode （str，可选）：标题格式- "Markdown", "HTML"，或 "None"默认值： "Markdown"
• disable_notification （bool，可选）：静默发送。违约： False

退货：

{
  "message_id": 12345,
  "chat_id": -1001234567890,
  "date": "2024-01-15T10:30:00",
  "caption": "Photo caption text",
  "photo": {
    "file_id": "AgACAgIAAxkBAAMCY...",
    "file_unique_id": "AQADAgATxxx",
    "width": 1280,
    "height": 720,
    "file_size": 102400
  },
  "link": "https://t.me/mychannel/12345"
}

edit_message

编辑频道中现有的TEXT-ONLY消息。

重要： 这仅适用于短信。如果消息中包含照片，请使用 edit_message_caption 相反。

参数：

• channel_id （str，必填）：频道用户名或聊天ID
• message_id （int，必填）：要编辑的消息的ID
• new_text （str，必填）：新消息文本
• parse_mode （str，可选）：文本格式。违约： "Markdown"

edit_message_caption

编辑频道中现有PHOTO消息的标题。

重要： 这仅适用于带有媒体的消息。对于纯文本消息，请使用 edit_message 相反。

参数：

• channel_id （str，必填）：频道用户名或聊天ID
• message_id （int，必填）：要编辑的照片消息的ID
• new_caption （str，必填）：新标题文本
• parse_mode （str，可选）：标题格式。违约： "Markdown"

delete_message

从频道中删除消息。

参数：

• channel_id （str，必填）：频道用户名或聊天ID
• message_id （int，必填）：要删除的消息的ID

search_messages

在本地缓存中搜索消息（在当前会话中发布/编辑的消息）。

注： Telegram Bot API不支持本机消息搜索。这将搜索本地缓存的邮件。

参数：

• channel_id （str，必填）：频道用户名或聊天ID
• query （str，可选）：搜索查询（不区分大小写）。如果为None，则返回所有缓存的消息
• limit （int，可选）：返回的最大结果。违约： 10

get_channel_info

获取有关Telegram频道的信息。

参数：

• channel_id （str，必填）：频道用户名或聊天ID

退货：

{
  "id": -1001234567890,
  "title": "My Channel",
  "username": "mychannel",
  "type": "channel",
  "description": "Channel description",
  "invite_link": "https://t.me/mychannel",
  "member_count": 1234,
  "status": "success"
}

发展

运行测试

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run tests with verbose output
pytest -v

# Run tests with coverage
pytest --cov=telegram_bot --cov-report=html

# Run specific test
pytest tests/test_telegram.py::TestTelegramClient::test_publish_message

代码质量

# Type checking
mypy telegram_bot

# Linting
ruff check .

# Formatting
ruff format .

在本地运行服务器

出于测试目的，您可以直接运行服务器：

# Set your bot token
export TELEGRAM_BOT_TOKEN="your-token"

# Run the server
python -m telegram_bot

服务器将按照MCP协议启动并通过stdio进行通信。

建筑

部件结构

telegram-bot-mcp/
├── main.py                  # Entry point for the server
├── telegram_bot/
│   ├── __init__.py          # Package initialization
│   ├── server.py            # FastMCP server implementation with tool decorators
│   └── telegram_bot_client.py  # TelegramBotClient wrapper
└── tests/
    └── test_telegram.py     # Comprehensive tests

设计模式

• Singleton客户端：全球 TelegramBotClient 跨工具调用重用实例
• 异步优先：所有I/O操作都是异步的，以获得更好的性能
• 错误处理：带有状态信息的优雅错误响应
• 本地缓存：用于搜索功能的消息缓存（由于Telegram API不支持搜索）

局限性

1. 消息类型和编辑:

   • 短信：使用 edit_message （不适用于照片消息）
   • 照片信息：使用 edit_message_caption （不适用于纯文本消息）
   • 您不能将短信更改为照片，反之亦然
   • 机器人只能编辑它自己发送的消息

2. 邮件搜索：仅搜索当前会话中本地缓存的消息（Telegram Bot API限制）

   • 消息在当前会话期间缓存在内存中
   • 服务器重新启动时，缓存被清除
   • 如果你知道message_id，你仍然可以编辑以前会话的消息

3. 消息检索：Telegram Bot API不提供通过ID获取任意消息的方法

4. 机器人权限：Bot必须是具有适当权限的频道管理员：

   • 发布消息
   • 编辑消息
   • 删除消息

5. 编辑时间限制：Telegram对编辑消息有48小时的限制

6. 速率限制：Telegram对机器人程序API调用强制执行速率限制

故障排除

“需要Telegram机器人令牌”错误

确保您已设置 TELEGRAM_BOT_TOKEN 环境变量或在MCP客户端中配置它。

“未找到聊天”错误

• 对于公共频道，请确保使用 @channelname 格式
• 对于私人频道，使用数字聊天ID（例如。， -1001234567890)
• 验证机器人是否已作为管理员添加到频道中

“权限不足，无法发送消息”错误

机器人程序需要具有以下频道的管理员权限：

• 发布消息
• 编辑消息
• 删除消息

“消息无法编辑”错误

这通常意味着：

1. 消息类型的编辑方法错误：使用 edit_message_caption 对于照片， edit_message 对于文本
2. Bot未发送消息：机器人只能编辑自己发送的消息
3. 消息太旧：Telegram对编辑消息有48小时的限制

许可证

MIT许可证-有关详细信息，请参阅许可证文件

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 添加新功能的测试
4. 确保所有测试通过
5. 提交拉取请求

资源

• 模型上下文协议文档
• MCP Python SDK
• Telegram Bot API文档
• python电报机器人库

支持

对于问题和疑问：

• GitHub问题： 报告错误
• MCP故障： 加入社区