aiogram-mcp

aiogram-mcp

通过模型上下文协议将你的 Telegram 机器人连接到 AI Agent。

aiogram-mcp 可将任意 aiogram 机器人变成 MCP 服务。随后，Claude Desktop 等 AI 客户端便可通过你现有的机器人发送消息、读取聊天记录、创建交互式菜单并实时响应事件，无需重写任何处理程序。

为什么选择 aiogram-mcp？

大多数 Telegram MCP 服务都只是包含 3-5 个工具的简单封装。aiogram-mcp 更进一步：

• 30 个工具 — 消息发送、富媒体、管理、交互式键盘、事件订阅、广播
• 7 个资源 — 机器人信息、配置、聊天列表、消息历史记录、事件队列、文件元数据、审计日志
• 3 个提示词 — 现成的管理、公告和用户报告工作流
• 结构化输出 — 每个工具都会返回带有 outputSchema 的类型化 Pydantic 模型，便于程序解析
• 实时事件 — 机器人通过 MCP 通知将 Telegram 事件推送给 AI 客户端（无需轮询）
• 交互式消息 — AI Agent 可创建内联键盘菜单、处理按钮点击并编辑消息
• 速率限制 — 内置令牌桶可防止 Telegram 429 错误
• 权限级别 — 可限制 AI Agent 仅具备只读、消息发送、管理或完整管理员权限
• 审计日志记录 — 通过时间戳和参数跟踪每次工具调用
• 无需重写 — 只需在现有机器人中添加 5 行代码，并保留所有处理程序

工作原理

Telegram users                Your aiogram bot              AI agent (Claude Desktop)
      |                             |                              |
      |  send messages, tap buttons |                              |
      | --------------------------> |                              |
      |                             |  MCP server (stdio or SSE)   |
      |                             | <------------------------->  |
      |                             |  tools / resources / events  |
      |                             |                              |
      |  bot replies, shows menus   |   send_message, edit, ban    |
      | <-------------------------- | <--------------------------- |

机器人会继续正常为 Telegram 用户提供服务。MCP 服务与机器人并行运行，让 AI Agent 可通过工具和资源访问同一个机器人。

安装

pip install aiogram-mcp

需要 Python 3.10+ 和 aiogram 3.20+。

快速开始

1. 将 aiogram-mcp 添加到你的机器人

import asyncio
from aiogram import Bot, Dispatcher
from aiogram_mcp import AiogramMCP, EventManager, MCPMiddleware

bot = Bot(token="YOUR_BOT_TOKEN")
dp = Dispatcher()

# Middleware tracks chats, users, message history, and events
event_manager = EventManager()
middleware = MCPMiddleware(event_manager=event_manager)
dp.message.middleware(middleware)
dp.callback_query.middleware(middleware)  # for interactive buttons

# Register your normal handlers here
# @dp.message(...)
# async def my_handler(message): ...

# Create the MCP server
mcp = AiogramMCP(
    bot=bot,
    dp=dp,
    name="my-bot",
    middleware=middleware,
    event_manager=event_manager,
    allowed_chat_ids=[123456789],  # optional: restrict which chats AI can access
)

async def main():
    await mcp.run_alongside_bot(transport="stdio")

asyncio.run(main())

2. 连接 Claude Desktop

将以下内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "my-telegram-bot": {
      "command": "python",
      "args": ["path/to/your/bot.py"],
      "env": {
        "BOT_TOKEN": "123456:ABC-DEF..."
      }
    }
  }
}

现在，Claude 可以通过你的 Telegram 机器人发送消息、读取历史记录、创建按钮菜单并响应事件。

内置工具

消息发送（5 个工具）

工具	说明
send_message	发送带有 HTML/Markdown 格式的文本
send_photo	通过 URL 发送照片，可选添加说明文字
forward_message	在聊天之间转发消息
delete_message	删除消息
pin_message	在聊天中置顶消息

交互式消息（3 个工具）

工具	说明
send_interactive_message	发送带有内联键盘按钮（回调或 URL）的消息
edit_message	编辑现有消息的文本和/或键盘
answer_callback_query	通过弹出提示或警告响应按钮点击

用户（3 个工具）

工具	说明
get_bot_info	获取机器人元数据（用户名、功能）
get_chat_member_info	获取用户在聊天中的角色和个人资料
get_user_profile_photos	获取用户的个人资料照片

聊天（6 个工具）

工具	说明
get_chat_info	获取聊天元数据（标题、类型、描述）
get_chat_members_count	获取聊天中的成员数量
ban_user	封禁用户（永久或临时）
unban_user	解除对用户的封禁
set_chat_title	更改聊天标题
set_chat_description	更改聊天描述

富媒体（10 个工具）

工具	描述
send_document	通过 URL 发送文件/文档，可选择添加说明
send_voice	通过 URL 发送语音消息
send_video	通过 URL 发送视频，可选择添加说明
send_animation	通过 URL 发送 GIF/动画
send_audio	通过 URL 发送音频/音乐，并附带表演者和标题
send_sticker	通过 file_id 或 URL 发送贴纸
send_video_note	通过 URL 发送圆形视频消息
send_contact	发送包含电话号码和姓名的联系人
send_location	发送地理位置标记
send_poll	创建包含多个选项的投票

事件（2 个工具）

工具	描述
subscribe_events	通过聊天/类型筛选条件订阅实时事件
unsubscribe_events	移除订阅

广播（1 个工具，需主动启用）

工具	描述
broadcast	向多个聊天发送消息（需要 enable_broadcast=True）

MCP 资源

AI Agent 无需调用工具即可访问的只读数据：

URI	描述
telegram://bot/info	机器人用户名、ID 和功能
telegram://config	服务名称和允许的聊天 ID
telegram://chats	包含元数据的活动聊天列表
telegram://chats/{chat_id}/history	聊天中的最近 50 条消息
telegram://events/queue	事件队列，ID 自动递增
telegram://files/{file_id}	文件元数据（大小、路径、唯一 ID）
telegram://audit/log	工具调用审计日志（需主动启用）

MCP 提示词

为 AI Agent 提供结构化上下文的预构建工作流：

提示词	参数	功能
moderation_prompt	chat_id、user_id、reason	获取用户信息和消息历史，建议警告、禁言或封禁
announcement_prompt	topic、audience?、tone?	起草格式化的 Telegram 公告
user_report_prompt	chat_id、user_id	汇总完整的用户活动报告

实时事件流

AI Agent 无需轮询。机器人会自动推送事件：

Telegram message arrives
    → MCPMiddleware captures it
        → EventManager stores it (type: "message", "command", or "callback_query")
            → MCP notification sent to subscribed clients
                → AI agent reads telegram://events/queue

AI Agent 调用一次 subscribe_events 后，每当有新事件符合其筛选条件时，就会收到推送通知。

交互式消息

AI Agent 可以在 Telegram 中构建完整的交互式 UI——菜单、确认提示和多步骤向导：

AI Agent 发送带按钮的消息：

┌─────────────────────────┐
│ Confirm deployment?     │
│                         │
│  [✅ Yes]  [❌ No]      │
│  [📖 View docs]        │
└─────────────────────────┘

用户点击按钮 → 事件出现在队列中 → AI Agent 作出响应：

┌─────────────────────────┐
│ ✅ Deployed!            │
│                         │
│  [📋 View logs]        │
└─────────────────────────┘

机器人需要使用 dp.callback_query.middleware(middleware) 来捕获按钮点击。

安全控制

mcp = AiogramMCP(
    bot=bot,
    dp=dp,
    allowed_chat_ids=[123456789, -1001234567890],  # restrict AI access
    enable_broadcast=True,            # opt-in for broadcast tool
    max_broadcast_recipients=500,     # safety limit
)

• allowed_chat_ids — AI 只能与列表中的聊天互动。默认值：所有聊天。
• enable_broadcast — 出于安全考虑，广播工具默认禁用。
• max_broadcast_recipients — 限制单次广播中的聊天数量。

高级配置

速率限制

mcp = AiogramMCP(
    bot=bot, dp=dp,
    rate_limit=30,  # requests/sec (default), 0 to disable
)

内置令牌桶速率限制器可防止 Telegram 429 错误。所有发出的 API 调用都会自动控制速率。

权限级别

mcp = AiogramMCP(
    bot=bot, dp=dp,
    permission_level="messaging",  # read + messaging tools only
)

级别	访问权限
read	机器人信息、聊天信息、用户资料
messaging	读取权限 + 发送消息、照片、媒体和交互式消息
moderation	消息权限 + 删除、置顶、封禁、解除封禁和聊天设置
admin	完全访问权限，包括广播和事件订阅

审计日志

mcp = AiogramMCP(
    bot=bot, dp=dp,
    enable_audit=True,
    audit_log_size=1000,
)

每次工具调用都会记录日志。可通过 telegram://audit/log 资源访问。

示例

示例	传输方式	功能
basic_bot.py	stdio	完整设置，包含中间件、事件和回调跟踪
incident_alert_bot.py	SSE	启用广播的运维机器人，用于发送事件通知

开发

git clone https://github.com/Py2755/aiogram-mcp.git
cd aiogram-mcp
pip install -e ".[dev]"

pytest -v          # ~228 tests
ruff check aiogram_mcp tests examples
mypy aiogram_mcp   # strict mode

许可证

MIT。请参阅 LICENSE。