Py2755/aiogram-mcp

**Connect your Telegram bot to AI agents via the Model Context Protocol.**
aiogram-mcp turns any aiogram bot into an MCP server. AI clients like Claude Desktop can then send messages, read chat history, build interactive menus, and react to events in real time — all through your existing bot, without rewriting a single handler.
Why aiogram-mcp?
Most Telegram MCP servers are thin wrappers with 3-5 tools. aiogram-mcp goes further:
- **30 tools** — messaging, rich media, moderation, interactive keyboards, event subscriptions, broadcasting
- **7 resources** — bot info, config, chat lists, message history, event queue, file metadata, audit log
- **3 prompts** — ready-made moderation, announcement, and user report workflows
- **Structured output** — every tool returns typed Pydantic models with outputSchema for programmatic parsing
- **Real-time events** — the bot pushes Telegram events to AI clients via MCP notifications (no polling)
- **Interactive messages** — AI agents create inline keyboard menus, handle button presses, edit messages
- **Rate limiting** — built-in token bucket prevents Telegram 429 errors
- **Permission levels** — restrict AI agents to read-only, messaging, moderation, or full admin access
- **Audit logging** — track every tool invocation with timestamps and arguments
- **Zero rewrite** — add 5 lines to your existing bot, keep all your handlers
How It Works
The bot runs normally for Telegram users. The MCP server runs alongside it, giving AI agents access to the same bot via tools and resources.
Installation
Requires Python 3.10+ and aiogram 3.20+.
Quickstart
1. Add aiogram-mcp to your bot
2. Connect Claude Desktop
Add to your claude_desktop_config.json:
Now Claude can send messages, read history, create button menus, and react to events in your Telegram bot.
Built-in Tools
Messaging (5 tools)
| Tool | Description |
|------|-------------|
| send_message | Send text with HTML/Markdown formatting |
| send_photo | Send a photo by URL with optional caption |
| forward_message | Forward a message between chats |
| delete_message | Delete a message |
| pin_message | Pin a message in a chat |
Interactive Messages (3 tools)
| Tool | Description |
|------|-------------|
| send_interactive_message | Send a message with inline keyboard buttons (callback or URL) |
| edit_message | Edit text and/or keyboard of an existing message |
| answer_callback_query | Respond to a button press with a toast or alert |
Users (3 tools)
| Tool | Description |
|------|-------------|
| get_bot_info | Get bot metadata (username, capabilities) |
| get_chat_member_info | Get a user's role and profile in a chat |
| get_user_profile_photos | Get a user's profile photos |
Chats (6 tools)
| Tool | Description |
|------|-------------|
| get_chat_info | Get chat metadata (title, type, description) |
| get_chat_members_count | Get number of members in a chat |
| ban_user | Ban a user (permanent or temporary) |
| unban_user | Unban a user |
| set_chat_title | Change the chat title |
| set_chat_description | Change the chat description |
Rich Media (10 tools)
| Tool | Description |
|------|-------------|
| send_document | Send a file/document by URL with optional caption |
| send_voice | Send a voice message by URL |
| send_video | Send a video by URL with optional caption |