Purpose
aiogram-mcp is an MCP (Model Context Protocol) server middleware used to connect aiogram-based Telegram bots to AI agents. It turns any aiogram bot into an MCP server, enabling AI clients such as Claude Desktop to send messages, read chat history, build interactive menus, and respond to events in real time through the existing bot, without rewriting any handler. The bot runs as usual on the Telegram user side, while the MCP server runs alongside it, exposing the same bot's tools and resources to AI agents.
Main capabilities
- About 30 tools: covering message sending (5), interactive messages (3), users (3), chats (6), rich media (10), events (2), and broadcast (1, disabled by default/requires explicit enablement).
- 7 resources: bot info, configuration, chat list, message history, event queue, file metadata, audit log, which AI agents can read without calling tools.
- 3 prompts: built-in moderation, announcement, and user report workflows, providing structured context for AI agents.
- Structured output: each tool returns a typed Pydantic model with an outputSchema, making programmatic parsing easy.
- Real-time events: the bot pushes Telegram events to AI clients via MCP notifications, with no polling required; after an AI agent calls subscribe_events once, it can receive pushes matching the filter criteria.
- Interactive messages: AI agents can create inline keyboard menus, handle button clicks, and edit messages, enabling complete interactive interfaces such as menus, confirmations, and multi-step wizards.
- Security and control: built-in token bucket rate limiting prevents Telegram 429 errors; supports permission levels (read-only, message, moderation, full admin); records the timestamp and parameters of every tool call, accessible via the telegram://audit/log resource.
- Security restriction options: allowed_chat_ids limits the chats the AI can interact with (all chats by default); enable_broadcast disables the broadcast tool by default; max_broadcast_recipients limits the maximum number of chats per broadcast.
Usage
Requires Python 3.10+ and aiogram 3.20+. Add the corresponding code to the existing bot (about 5 lines), and configure the connection in claude_desktop_config.json, and Claude can then send messages, read history, create button menus, and respond to events. To capture button clicks, the bot needs to register dp.callback_query.middleware(middleware).
Applicable scenarios
Scenarios where AI agent control capabilities are added to an existing aiogram Telegram bot, for example letting the AI send messages on its behalf, read chat history, create interactive menus, subscribe to and respond to real-time events, or perform content moderation or broadcast tasks, while keeping the original handlers unchanged.
Limitations
The specific installation commands, configuration examples, and detailed parameters for each tool are not fully provided in the supplied materials and are not available for now; the license is MIT.
